From 6b6797f60fe06235923f10e7deee2b8f370eca8c Mon Sep 17 00:00:00 2001 From: Dylan Shade <63427984+dpshade@users.noreply.github.com> Date: Mon, 15 Sep 2025 15:18:20 -0400 Subject: [PATCH 1/4] docs: update style.css and hyperbeam-devices.md for improved clarity and organization - Commented out border styles in style.css for cleaner presentation. - Enhanced hyperbeam-devices.md by adding new sections for Authentication Ecosystem, Data Discovery Engine, and Data Replication Engine. - Consolidated security and authentication devices into a single entry for better understanding. - Improved data management devices section for clarity on capabilities. --- docs/assets/stylesheets/style.css | 10 +- docs/build/devices/auth-ecosystem-at-1-0.md | 285 ++++++++++++ docs/build/devices/data-discovery-at-1-0.md | 340 ++++++++++++++ docs/build/devices/data-replication-at-1-0.md | 428 ++++++++++++++++++ docs/build/devices/hyperbeam-devices.md | 6 +- docs/build/devices/index.md | 171 +++++++ 6 files changed, 1234 insertions(+), 6 deletions(-) create mode 100644 docs/build/devices/auth-ecosystem-at-1-0.md create mode 100644 docs/build/devices/data-discovery-at-1-0.md create mode 100644 docs/build/devices/data-replication-at-1-0.md create mode 100644 docs/build/devices/index.md diff --git a/docs/assets/stylesheets/style.css b/docs/assets/stylesheets/style.css index ad20bba6e..b229f271c 100644 --- a/docs/assets/stylesheets/style.css +++ b/docs/assets/stylesheets/style.css @@ -114,7 +114,7 @@ h6 { } .md-content h2 { - border-top: 1px solid var(--border-color); + /* border-top: 1px solid var(--border-color); */ padding-top: 1.5rem; } @@ -122,20 +122,20 @@ h6 { h4, h5, h6 { - border-top: 1px solid var(--border-color-alt); + /* border-top: 1px solid var(--border-color-alt); */ padding-top: 1rem; } /* Match border opacity to tabs border in dark mode */ [data-md-color-scheme="slate"] .md-content h2 { - border-top: 1px solid var(--border-color) !important; + /* border-top: 1px solid var(--border-color) !important; */ } [data-md-color-scheme="slate"] .md-content h3, [data-md-color-scheme="slate"] h4, [data-md-color-scheme="slate"] h5, [data-md-color-scheme="slate"] h6 { - border-top: 1px solid var(--border-color) !important; + /* border-top: 1px solid var(--border-color) !important; */ } /* --- Text Elements --- */ @@ -2053,7 +2053,7 @@ kbd { [data-md-color-scheme="slate"] h4, [data-md-color-scheme="slate"] h5, [data-md-color-scheme="slate"] h6 { - border-top: 1px solid var(--border-color) !important; + /* border-top: 1px solid var(--border-color) !important; */ } [data-md-color-scheme="slate"] .md-tabs { diff --git a/docs/build/devices/auth-ecosystem-at-1-0.md b/docs/build/devices/auth-ecosystem-at-1-0.md new file mode 100644 index 000000000..fee256ce2 --- /dev/null +++ b/docs/build/devices/auth-ecosystem-at-1-0.md @@ -0,0 +1,285 @@ +# Device: Authentication Ecosystem (~auth-hook@1.0, ~secret@1.0, ~cookie@1.0, ~http-auth@1.0) + +## Overview + +The HyperBEAM Authentication Ecosystem provides a comprehensive suite of devices that enable wallet-less blockchain applications through server-side key management and transparent authentication. This ecosystem eliminates traditional blockchain UX friction by handling cryptographic operations transparently while maintaining security through trusted execution environments. + +The ecosystem consists of four interconnected devices: + +- **`~auth-hook@1.0`**: Main authentication interceptor and request signer +- **`~secret@1.0`**: Wallet generation and secret management +- **`~cookie@1.0`**: Session-based authentication via HTTP cookies +- **`~http-auth@1.0`**: HTTP Basic authentication with PBKDF2 key derivation + +## Core Concept: Zero-Friction Authentication + +The authentication ecosystem transforms blockchain application UX from multi-step wallet connection processes into single-click experiences. Users interact with decentralized applications exactly like traditional web applications, while HyperBEAM handles all cryptographic operations server-side. + +## Primary Device: ~auth-hook@1.0 + +### Authentication Hook Overview +The auth-hook device serves as the main entry point for wallet-less authentication, intercepting HTTP requests and automatically signing them with node-hosted wallets according to operator configuration. + +### Key Functions + +#### `request` +Processes incoming requests through a configured secret provider: +* **Action:** Intercepts HTTP requests containing the `&!` parameter +* **Process Flow:** + 1. Detect `&!` pattern in URL parameters + 2. Find and validate secret provider configuration + 3. Check relevance based on `when` conditions + 4. Generate or retrieve authentication secrets via provider + 5. Create wallet if needed through `~secret@1.0` + 6. Sign request and message sequences + 7. Finalize with provider-specific post-processing + +### Configuration Parameters + +#### Secret Provider Integration +```text +"secret-provider": { + "device": "cookie@1.0", + "generate-path": "generate", + "finalize-path": "finalize" +} +``` + +#### Activation Conditions +```text +"when": { + "committers": "uncommitted" | "always" | ["address1", "address2"], + "keys": "always" | ["authorization", "custom-header"] +} +``` + +## Supporting Device: ~secret@1.0 + +### Secret Management Overview +The secret device manages wallet creation, storage, and commitment operations for node-hosted secrets with configurable access control and persistence modes. + +### Key Functions + +#### `generate` +Creates new wallets with authentication setup: + +* **Parameters:** `access-control`, `persist`, `controllers`, `required-controllers` +* **Persistence Modes:** + - `client`: Generated server-side, returned to client + - `in-memory`: Session-based storage + - `non-volatile`: Persistent disk storage + +#### `commit` +Signs messages using hosted secrets: + +* **Access Control:** Dual-layer security through access-control messages and controller verification +* **Multi-Signature:** Supports required-controllers threshold + +#### `export` / `sync` +Manages wallet portability and node synchronization: + +* **Export:** Access-controlled wallet extraction +* **Sync:** Cross-node wallet synchronization + +### Integration with Auth-Hook + +1. Auth-hook generates/retrieves secrets via provider +2. Passes secrets to `~secret@1.0` for wallet operations +3. Uses generated wallets for request signing +4. Maintains session consistency through provider + +## Provider Device: ~cookie@1.0 + +### Cookie Authentication Overview +Manages HTTP cookie-based authentication and session persistence, implementing the generator interface for auth-hook integration. + +### Key Functions + +#### Generator Interface Implementation +```text +generate: Creates or retrieves authentication secrets from cookies +finalize: Adds set-cookie headers to response sequences +``` + +#### Cookie Management + +* **Formats:** set-cookie (full attributes), cookie (simple), structured-fields (internal) +* **Security:** HMAC-SHA256 commitments, HTTPOnly, Secure, SameSite support +* **Storage:** `wallet-
` and `secret-` cookie patterns + +### Session Flow + +1. **Initial Request:** Generate secret, store in cookie, return Set-Cookie header +2. **Subsequent Requests:** Extract secret from cookie, validate, use for signing +3. **Session Persistence:** Maintain authentication across browser sessions + +## Provider Device: ~http-auth@1.0 + +### HTTP Authentication Overview +Implements HTTP Basic authentication with PBKDF2 key derivation, providing enterprise-grade authentication for protected resources. + +### Key Functions + +#### `generate` +Processes HTTP Authorization headers: + +* **PBKDF2 Parameters:** 1,200,000 iterations, SHA256, 64-byte keys +* **Security:** 2x OWASP recommendation, ~5-10 derivations/second +* **401 Response:** Triggers browser authentication prompts + +#### Authentication Flow + +1. **No Credentials:** Return 401 with WWW-Authenticate header +2. **Basic Auth:** Extract and decode Authorization header +3. **Key Derivation:** Apply PBKDF2 to credentials +4. **Secret Generation:** Use derived key for signing operations + +## Device Integration & Synergy + +### Complete Authentication Workflow +```text +HTTP Request → Auth-Hook → Provider (Cookie/HTTP-Auth) → Secret → Wallet → Signed Response + ↓ ↓ ↓ ↓ ↓ ↓ + &! Parameter Intercept Generate Secret Create Key Sign Msg Set Cookie +``` + +### Integration with Core Devices + +#### With Process Device (`~process@1.0`) + +- Automatic signing of process communications +- Seamless AO process interaction without wallet setup +- Transparent message commitment in ANS-104 format + +#### With Query Device (`~query@1.0`) +- Authenticated data discovery and search +- User-specific query results based on wallet identity +- Access-controlled message retrieval + +#### With Copycat Device (`~copycat@1.0`) +- Authenticated data replication from external sources +- Signed import operations for data integrity +- Identity-based data synchronization + +#### With Meta Device (`~meta@1.0`) +- Node configuration for authentication providers +- Access control policy management +- Resource allocation for auth operations + +### Cross-Device Authentication Patterns + +#### Multi-Provider Support +```text +"on": { + "request": [ + { + "device": "auth-hook@1.0", + "secret-provider": {"device": "cookie@1.0"} + }, + { + "device": "auth-hook@1.0", + "secret-provider": {"device": "http-auth@1.0"}, + "when": {"keys": ["authorization"]} + } + ] +} +``` + +#### Chained Authentication +```text +Cookie Auth → HTTP Auth → Secret Management → Process Interaction + ↓ ↓ ↓ ↓ + Session Enterprise Wallet Creation Signed Messages +``` + +## Security Architecture + +### Trust Model +- **Server-Trust:** Users trust HyperBEAM nodes for key management +- **TEE Integration:** Designed for Trusted Execution Environments +- **Cryptographic Auditability:** All operations create verifiable signatures +- **Key Isolation:** Private keys never leave server memory + +### Multi-Layer Security +1. **Provider Layer:** Cookie/HTTP authentication +2. **Access Control:** Configurable access-control messages +3. **Controller Verification:** Multi-signature support +4. **Request Signing:** RSA-PSS/HMAC cryptographic proofs + +### Security Best Practices +- HTTPS-only deployment +- Secure cookie attributes (HTTPOnly, Secure, SameSite) +- Strong PBKDF2 parameters +- Regular session key rotation +- Comprehensive audit logging + +## Performance Considerations + +### Optimization Strategies +- **In-Memory Caching:** Active wallet cache for sessions +- **Lazy Loading:** On-demand wallet retrieval from storage +- **Batch Operations:** Parallel message signing +- **Session Reuse:** Authentication state persistence + +### Scalability Metrics +- **Memory:** ~2KB per active session (in-memory mode) +- **Computation:** RSA signing ~5ms, HMAC ~0.1ms per operation +- **Throughput:** ~10K concurrent sessions per GB RAM +- **Cookie Limits:** 4KB browser limit for session data + +## Implementation Examples + +### Basic Cookie Authentication +```text +"on": { + "request": { + "device": "auth-hook@1.0", + "secret-provider": {"device": "cookie@1.0"} + } +} +``` + +### Enterprise HTTP Authentication +```text +"on": { + "request": { + "device": "auth-hook@1.0", + "secret-provider": { + "device": "http-auth@1.0", + "realm": "Protected Resources", + "iterations": 2000000 + } + } +} +``` + +### Multi-Signature Wallet Management +```text +"secret-provider": { + "device": "cookie@1.0", + "access-control": { + "device": "http-auth@1.0" + }, + "controllers": ["admin1", "admin2", "admin3"], + "required-controllers": 2 +} +``` + +## Error Handling & Recovery + +### Graceful Degradation +- Skip authentication if provider not found +- Return original request if relevance conditions not met +- Detailed error logging with context preservation +- Partial failure isolation in batch operations + +### Monitoring & Debugging +- Event-driven logging across all devices +- Performance metrics for auth operations +- Session tracking and analytics +- Security audit trail maintenance + +**Related Documentation:** +- [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture +- [Building Devices](./building-devices.md) - Creating custom devices +- [Core Devices Index](./index.md) - Complete device catalog \ No newline at end of file diff --git a/docs/build/devices/data-discovery-at-1-0.md b/docs/build/devices/data-discovery-at-1-0.md new file mode 100644 index 000000000..7fdde3059 --- /dev/null +++ b/docs/build/devices/data-discovery-at-1-0.md @@ -0,0 +1,340 @@ +# Device: Data Discovery Engine (~query@1.0) + +## Overview + +The `~query@1.0` device serves as HyperBEAM's primary data discovery engine, providing flexible search capabilities over cached messages with multiple matching modes and return formats. It enables efficient data retrieval, supports GraphQL queries, and integrates seamlessly with the broader HyperBEAM ecosystem for comprehensive data workflows. + +This device is essential for: + +- Searching cached messages by key-value pairs with flexible filtering +- Supporting various query modes and return formats for different use cases +- Providing GraphQL query capabilities for complex data operations +- Enabling efficient data discovery in conjunction with replication systems + +## Core Concept: Message Discovery + +The query device operates as a sophisticated search interface over a node's cached messages, supporting various matching strategies and flexible return formats. It can search by specific keys, all message fields, or custom specifications with configurable filtering and exclusion rules, making it the central hub for data discovery in HyperBEAM applications. + +## Key Functions (Keys) + +### `all` +Searches for all keys and values in the request message against cached data. + +* **`GET /~query@1.0/all`** + * **Action:** Matches all keys in the request against cached messages + * **Parameters:** + * `exclude`: List of keys to exclude from search (default: ["path", "commitments", "return", "exclude", "only"]) + * `return`: Return format specification (paths, messages, count, first-path, first-message, boolean) + * **Response:** Query results in specified format + +### `base` +Searches for all keys and values in the base message. + +* **`GET /~query@1.0/base`** + * **Action:** Matches all keys in the base message against cached messages + * **Usage:** Useful when query parameters are pre-configured in the base message + * **Response:** Query results based on base message keys + +### `only` +Searches for specific keys specified in the request. + +* **`GET /~query@1.0/only`** + * **Parameters:** + * `only`: Key specification in multiple formats: + * Binary: Comma-separated key names ("key1,key2,key3") + * Map: Direct match specification {"key": "value"} + * List: Array of keys to extract from request/base + * **Response:** Results matching only specified keys + +### `graphql` +Executes GraphQL queries against the node's data. + +* **`POST /~query@1.0/graphql`** + * **Action:** Processes GraphQL queries for advanced data retrieval + * **Integration:** Delegates to `dev_query_graphql` module + * **Request Body:** GraphQL query with variables and operation names + * **Response:** GraphQL-formatted results with schema validation + +### `has_results` +Determines if a GraphQL response contains transaction results. + +* **`GET /~query@1.0/has_results`** + * **Action:** Validates GraphQL responses for gateway client configuration + * **Usage:** Enables HyperBEAM's multirequest configuration + * **Response:** Boolean indicating presence of results + +## Return Format Specifications + +### `paths` (Default) +Returns list of message identifiers for efficient reference: +```text +{"return": "paths"} +// Response: ["msg_id_1", "msg_id_2", "msg_id_3"] +``` + +### `messages` +Returns complete message objects for detailed analysis: +```text +{"return": "messages"} +// Response: [complete_message_1, complete_message_2, ...] +``` + +### `count` +Returns numerical count of matches for analytics: +```text +{"return": "count"} +// Response: 42 +``` + +### `first-path` / `first-message` +Returns first match for single-result queries: +```text +{"return": "first-message"} +// Response: {first_matching_message} +``` + +### `boolean` +Returns existence check for conditional logic: +```text +{"return": "boolean"} +// Response: true +``` + +## Core Dependencies & Architecture + +### Cache Layer (`~cache@1.0`) +Primary data source providing: +- Indexed access to stored messages +- Match functionality for key-value searches +- Message loading and serialization management +- Performance optimization through caching strategies + +### Storage Layer (`~store@1.0`) +Underlying persistent storage: +- Houses actual message data with durability guarantees +- Supports various storage backends (LMDB, RocksDB) +- Provides indexing capabilities for efficient queries +- Manages storage partitioning and conflict resolution + +### Message Processing (`~message@1.0`) +Message format handling: +- Validates message structure and format compliance +- Handles commitment and signature processing +- Manages message serialization across different formats +- Ensures data integrity during query operations + +## Device Integration & Synergy + +### With Copycat Device (`~copycat@1.0`) +Comprehensive data lifecycle management: + +**Data Pipeline:** +```text +External Source → Copycat → Cache → Query → Application + ↓ ↓ ↓ ↓ ↓ + Remote Data Replication Storage Discovery Usage +``` + +**Workflow Integration:** +1. **Replication Phase:** Copycat imports external data into local cache +2. **Discovery Phase:** Query provides search and discovery over imported data +3. **Application Phase:** Combined pattern enables offline-first applications with complete datasets + +**Example Workflow:** +```text +// First: Replicate data from external source +POST /~copycat@1.0/graphql +{ + "tag": "App-Name", + "value": "MyApp" +} + +// Then: Query replicated data locally +GET /~query@1.0/all +{ + "tag": "App-Name", + "return": "count" +} +``` + +### With Authentication Ecosystem +Authenticated and access-controlled queries: + +**Protected Data Discovery:** +- Query operations can be protected by `~auth-hook@1.0` +- Enables user-specific data discovery based on wallet identity +- Supports access-controlled search patterns with fine-grained permissions + +**Identity-Based Queries:** +```text +GET /~query@1.0/all +Authorization: Bearer +{ + "owner": "", + "return": "messages" +} +``` + +### With Process Device (`~process@1.0`) +Process state discovery and analysis: + +**Process Message Discovery:** +```text +GET /~query@1.0/all +{ + "action": "get-messages", + "return": "messages" +} +``` + +**Historical Analysis:** +- Query process message sequences for state reconstruction +- Analyze process evolution over time +- Support process debugging and audit workflows + +### With Meta Device (`~meta@1.0`) +Node configuration and resource management: +- Query device configuration through meta device +- Resource allocation for query operations +- Performance monitoring and optimization + +## Advanced Query Patterns + +### Multi-Key Filtering +All specified keys must match (AND logic): +```text +{ + "type": "message", + "device": "process@1.0", + "status": "active", + "return": "count" +} +``` + +### Nested Message Support +Search within nested message structures: +```text +{ + "nested.field": "value", + "complex.path.data": "target", + "return": "paths" +} +``` + +### Exclusion-Based Queries +Filter out unwanted data during search: +```text +{ + "type": "message", + "exclude": ["internal-timestamp", "debug-info", "system-metadata"], + "return": "messages" +} +``` + +### Key Priority Resolution +When using key lists in `only` mode: +1. Search in request message first +2. Fall back to base message if not found +3. Filter out `not_found` values automatically +4. Maintain search order for result consistency + +## Performance Optimization + +### Caching Strategy +- **Index Utilization:** Leverages underlying store's native indexing capabilities +- **Memory Efficiency:** Returns paths by default to minimize memory usage +- **Lazy Loading:** Full messages loaded only when explicitly requested +- **Query Result Caching:** Frequently accessed queries cached for improved performance + +### Search Optimization +- **Filtered Matching:** Excludes metadata keys by default for focused searches +- **Batch Processing:** Supports bulk query operations for improved throughput +- **Parallel Processing:** Multiple queries can be processed concurrently +- **Resource Management:** Configurable limits prevent resource exhaustion + +## GraphQL Integration + +### Advanced Query Processing +The GraphQL integration provides: +- **Schema Validation:** Ensures query structure compliance +- **Variable Substitution:** Dynamic query parameterization +- **Result Formatting:** Standardized GraphQL response format +- **Error Handling:** Comprehensive error reporting and recovery + +### Gateway Client Support +The `has_results` function enables: +- **Response Validation:** Ensures query completeness across multiple nodes +- **Multirequest Configuration:** Supports distributed query coordination +- **Result Admissibility:** Determines acceptable response criteria +- **Consensus Building:** Enables distributed data discovery patterns + +## Security Considerations + +### Access Control +- **Cache Access:** Queries operate within node's security context +- **Key Filtering:** Sensitive keys excluded by default from search results +- **Resource Limits:** Underlying cache implements query limits and rate limiting +- **Authentication Integration:** Subject to node's access control policies + +### Data Privacy +- **Selective Exposure:** Configurable key exclusion for privacy protection +- **Audit Logging:** Query operations logged for security monitoring +- **Permission Enforcement:** Integration with authentication ecosystem +- **Secure Defaults:** Conservative security settings by default + +## Error Handling & Recovery + +### Graceful Degradation +- **Not Found:** Returns appropriate error codes or empty results based on return type +- **Invalid Specifications:** Clear error messages for malformed queries +- **Resource Exhaustion:** Graceful handling of resource limits +- **Partial Failures:** Robust error isolation in complex queries + +### Monitoring & Debugging +- **Query Analytics:** Performance metrics and usage statistics +- **Error Tracking:** Comprehensive error logging with context +- **Performance Monitoring:** Query execution time and resource usage tracking +- **Debug Support:** Detailed logging for development and troubleshooting + +## Implementation Examples + +### Basic Message Discovery +```text +GET /~query@1.0/all +{ + "device": "process@1.0", + "status": "active", + "return": "count" +} +``` + +### Complex Filtered Search +```text +GET /~query@1.0/only +{ + "only": "owner,type,timestamp", + "owner": "wallet-address", + "exclude": ["internal-data", "system-info"], + "return": "messages" +} +``` + +### GraphQL Query +```text +POST /~query@1.0/graphql +{ + "query": "query GetProcessMessages($processId: String!) { + messages(processId: $processId) { + id owner timestamp data + } + }", + "variables": {"processId": "process-123"} +} +``` + +--- + +**Related Documentation:** +- [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture +- [Building Devices](./building-devices.md) - Creating custom devices +- [Core Devices Index](./index.md) - Complete device catalog \ No newline at end of file diff --git a/docs/build/devices/data-replication-at-1-0.md b/docs/build/devices/data-replication-at-1-0.md new file mode 100644 index 000000000..481cb23c4 --- /dev/null +++ b/docs/build/devices/data-replication-at-1-0.md @@ -0,0 +1,428 @@ +# Device: Data Replication Engine (~copycat@1.0) + +## Overview + +The `~copycat@1.0` device orchestrates comprehensive data replication from external sources into HyperBEAM node caches. It serves as the primary data ingestion engine, supporting multiple replication strategies and sources while providing robust error handling, pagination management, and integration with the broader HyperBEAM ecosystem. + +This device is essential for: + +- Replicating messages from remote Arweave networks and GraphQL endpoints +- Building comprehensive local datasets for offline-first applications +- Enabling high-performance data access through local caching +- Supporting incremental and full data synchronization workflows + +## Core Concept: Data Ingestion Orchestration + +The copycat device acts as a sophisticated data ingestion orchestrator that fetches messages from various external sources and imports them into the local node's cache system. It supports multiple engines for different data sources, handles complex pagination scenarios, and provides comprehensive error recovery during large-scale replication operations. + +## Key Functions (Keys) + +### `graphql` +Fetches data from GraphQL endpoints for comprehensive replication. + +* **`POST /~copycat@1.0/graphql`** + * **Action:** Queries remote GraphQL endpoints and systematically indexes results locally + * **Parameters:** + * `query`: GraphQL query string or structured query specification + * `variables`: GraphQL query variables for parameterized queries + * `operationName`: Specific operation to execute in multi-operation queries + * `node`: Target GraphQL endpoint URL for data source + * **Processing:** Automatic pagination handling, message parsing, and cache integration + * **Response:** Total number of successfully indexed messages with batch statistics + +### `arweave` +Fetches data directly from Arweave nodes for block-level replication. + +* **`POST /~copycat@1.0/arweave`** + * **Action:** Connects directly to Arweave nodes and imports transaction/block data + * **Parameters:** + * `node`: Target Arweave node URL + * `from`: Starting block height for replication + * `to`: Ending block height for replication range + * `filter`: Transaction filtering criteria + * **Integration:** Uses `~arweave@2.9-pre` device for native Arweave communication + * **Response:** Replication status with imported message count and range coverage + +## Supported Data Sources & Engines + +### GraphQL Endpoints +**Comprehensive Gateway Support:** + +- Arweave Gateway GraphQL APIs (arweave.net, ar.io gateways) +- Custom GraphQL services and federated endpoints +- Multi-endpoint coordination for redundancy and performance + +**Query Generation Capabilities:** + +- Automatic query construction from filter parameters +- Custom GraphQL query support with variable interpolation +- Template-based query generation for common patterns + +### Arweave Nodes +**Direct Node Integration:** + +- Block-level data replication with height-based ranges +- Transaction indexing and comprehensive metadata capture +- Built-in caching mechanisms to prevent duplicate fetches +- Reverse chronological processing (latest to genesis) + +**Performance Optimization:** + +- Utilizes `~arweave@2.9-pre` device's native caching +- Efficient block processing with conflict detection +- Resource-aware processing for large-scale replication + +## Filter Types & Query Patterns + +### Tag-Based Filtering +Precise content filtering based on Arweave tags: +```text +{ + "tag": "Content-Type", + "value": "application/json" +} +``` + +### Owner-Based Filtering +User-specific data replication: +```text +{ + "owner": "wallet-address-here" +} +``` + +### Recipient-Based Filtering +Target-specific message replication: +```text +{ + "recipient": "target-address-here" +} +``` + +### Multi-Tag Complex Filtering +Advanced filtering with multiple criteria: +```text +{ + "tags": { + "App-Name": "MyApplication", + "Content-Type": "application/json", + "Version": "1.0" + } +} +``` + +### Comprehensive Replication +Complete dataset mirroring: +```text +{ + "all": true, + "node": "https://source-gateway.net/graphql" +} +``` + +## Data Processing Pipeline + +### Message Parsing & Validation +**Robust Data Processing:** + +1. **Result Processing:** Converts GraphQL responses to HyperBEAM message format +2. **Structure Validation:** Ensures message format compliance and integrity +3. **Error Isolation:** Logs and skips malformed messages without stopping batch processing +4. **Format Conversion:** Handles various input formats and standardizes output + +### Cache Integration & Storage +**Seamless Storage Integration:** + +1. **Write Operations:** Efficiently stores parsed messages in node cache +2. **Conflict Resolution:** Handles duplicate message scenarios intelligently +3. **Index Updates:** Maintains cache indexes for optimal query performance +4. **Transaction Safety:** Ensures data consistency during batch operations + +### Pagination & Batch Management +**Scalable Data Handling:** +```text +Fetch Batch → Parse Messages → Validate Format → Write to Cache → Update Progress + ↓ ↓ ↓ ↓ ↓ + GraphQL Message Structure Cache Store Statistics + Response Parsing Validation Integration Tracking +``` + +**Automatic Pagination:** +- Cursor-based pagination with seamless continuation +- Configurable batch sizes for optimal performance +- Progress tracking and resumption capabilities +- Memory-efficient streaming processing + +## Core Dependencies & Architecture + +### Gateway Client (`~gateway-client@1.0`) +**Remote Communication Engine:** +- GraphQL endpoint access and communication management +- Result parsing and protocol-specific data conversion +- Multi-endpoint federation and load balancing +- Response validation and comprehensive error handling + +### Arweave Integration (`~arweave@2.9-pre`) +**Native Arweave Communication:** +- Direct Arweave node communication for block data +- Transaction indexing with built-in caching mechanisms +- Height-based range queries for efficient replication +- Conflict detection and resolution for duplicate data + +### Cache Layer (`~cache@1.0`) +**Primary Replication Target:** +- Central storage for all imported messages +- Indexing infrastructure for imported data +- Message validation and integrity checking during import +- Storage conflict management and deduplication + +### Message Processing (`~message@1.0`) +**Format Standardization:** +- Converts external formats to HyperBEAM message standards +- Validates message structure before caching operations +- Handles commitment and signature processing for authenticated messages +- Manages serialization compatibility across different sources + +## Device Integration & Synergy + +### With Query Device (`~query@1.0`) +**Complete Data Lifecycle Management:** + +**Integrated Workflow:** +```text +1. Replication: Copycat → Cache (import external data) +2. Discovery: Query → Cache (search replicated content) +3. Analysis: Application → Query (utilize comprehensive dataset) +``` + +**Example Integration:** +```text +// Phase 1: Replicate application data +POST /~copycat@1.0/graphql +{ + "tag": "App-Name", + "value": "MyApp", + "node": "https://arweave.net/graphql" +} + +// Phase 2: Query replicated data locally +GET /~query@1.0/all +{ + "tag": "App-Name", + "return": "count" +} + +// Phase 3: Advanced analysis +GET /~query@1.0/only +{ + "only": "timestamp,owner", + "tag": "App-Name", + "return": "messages" +} +``` + +### With Authentication Ecosystem +**Authenticated Replication Operations:** + +**Identity-Based Replication:** +- Replicate user-specific data based on authenticated wallet identity +- Signed import operations for data integrity verification +- Access-controlled replication with fine-grained permissions + +**Multi-User Data Management:** +```text +// Authenticated replication request +POST /~copycat@1.0/graphql +Authorization: Bearer +{ + "owner": "", + "private": true +} +``` + +### With Process Device (`~process@1.0`) +**Process History Replication:** + +**Complete Process Reconstruction:** +- Import complete process message sequences for historical analysis +- Build offline process state snapshots for performance optimization +- Enable comprehensive process debugging and audit capabilities + +**Process-Specific Replication:** +```text +POST /~copycat@1.0/graphql +{ + "tags": { + "Data-Protocol": "ao", + "Type": "Message", + "Process": "" + } +} +``` + +### With Scheduler Device (`~scheduler@1.0`) +**Automated Replication Workflows:** + +**Scheduled Data Synchronization:** +```text +{ + "device": "scheduler@1.0", + "frequency": "1h", + "task": { + "device": "copycat@1.0", + "path": "graphql", + "incremental": true, + "filter": {"recent": "1h"} + } +} +``` + +**Continuous Integration Patterns:** +- Incremental updates for active datasets +- Full synchronization for periodic consistency checks +- Error recovery and retry mechanisms for failed operations + +### With Meta Device (`~meta@1.0`) +**Node Configuration Integration:** + +**Endpoint Management:** +- Replication endpoint configuration and credential management +- Resource allocation and performance tuning for replication operations +- Access control policy enforcement for external data sources + +**Resource Optimization:** +```text +{ + "replication-config": { + "max-concurrent": 5, + "batch-size": 100, + "timeout": 30000, + "retry-attempts": 3 + } +} +``` + +## Error Handling & Recovery + +### Comprehensive Error Management +**Multi-Level Error Handling:** + +**Parse Failures:** +- Individual message parse errors logged with detailed context +- Batch processing continues despite individual message failures +- Comprehensive error reporting for debugging and monitoring + +**Network Issues:** +- Automatic retry mechanisms for transient network failures +- Graceful degradation for partial connectivity issues +- Configurable timeout and retry policies +- Connection pooling and rate limiting + +**Cache Write Errors:** +- Transaction-level error isolation to prevent data corruption +- Detailed error logging with message context and stack traces +- Continuation of processing for remaining messages in batch +- Rollback capabilities for failed batch operations + +### Recovery & Resumption +**Robust Recovery Mechanisms:** +- Resume capability for interrupted replication operations +- Progress checkpointing for large-scale data migrations +- Duplicate detection and intelligent skipping +- Incremental synchronization for efficiency + +## Performance Optimization + +### Scalable Processing Architecture +**High-Performance Design:** + +**Batch Processing:** +- Configurable batch sizes for optimal memory usage +- Parallel processing of independent message batches +- Streaming architecture for minimal memory footprint +- Resource-aware processing with adaptive scaling + +**Progress Tracking:** +```text +{ + "total_processed": 15000, + "current_batch": 100, + "batch_failures": 2, + "success_rate": 99.87, + "estimated_remaining": "45 minutes" +} +``` + +**Memory Management:** +- Streaming message processing to minimize memory usage +- Lazy loading of message content for large datasets +- Garbage collection optimization for long-running operations +- Resource monitoring and automatic throttling + +### Performance Monitoring +**Comprehensive Metrics:** +- Processing rate and throughput monitoring +- Error rate tracking and trend analysis +- Resource utilization monitoring (CPU, memory, network) +- Performance bottleneck identification and optimization + +## Advanced Features & Extensibility + +### Custom Engine Support +**Extensible Architecture:** +- Plugin system for custom data source engines +- Protocol-specific optimization and handling +- Engine-specific configuration and tuning options +- Community-contributed engines for specialized sources + +### Multi-Source Coordination +**Sophisticated Source Management:** +```text +[ + { + "engine": "graphql", + "node": "https://gateway1.arweave.net/graphql", + "priority": 1 + }, + { + "engine": "graphql", + "node": "https://gateway2.arweave.net/graphql", + "priority": 2 + }, + { + "engine": "arweave", + "node": "https://node.arweave.net", + "priority": 3 + } +] +``` + +### Query Optimization +**Intelligent Query Management:** +- Efficient GraphQL query construction and optimization +- Variable interpolation and parameterization +- Result set optimization for improved performance +- Caching of frequently used query patterns + +## Security Considerations + +### Data Integrity & Validation +**Comprehensive Security Measures:** +- Source endpoint authentication and validation +- Data sanitization and structure validation for imported messages +- Rate limiting and resource protection against abuse +- Audit logging for all replication operations + +### Access Control Integration +**Security Framework Integration:** +- Subject to node's comprehensive access control policies +- Integration with authentication ecosystem for protected operations +- Resource allocation based on user privileges and quotas +- Secure credential management for external source access + +--- + +**Related Documentation:** +- [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture +- [Building Devices](./building-devices.md) - Creating custom devices +- [Core Devices Index](./index.md) - Complete device catalog \ No newline at end of file diff --git a/docs/build/devices/hyperbeam-devices.md b/docs/build/devices/hyperbeam-devices.md index 28804ebc0..72b35ec65 100644 --- a/docs/build/devices/hyperbeam-devices.md +++ b/docs/build/devices/hyperbeam-devices.md @@ -29,13 +29,17 @@ HyperBEAM includes many preloaded devices that provide core functionality. Some * [`~relay@1.0`](./relay-at-1-0.md): Forwards messages between AO nodes or to external HTTP endpoints. * [`~json@1.0`](./json-at-1-0.md): Provides access to JSON data structures. * [`~message@1.0`](./message-at-1-0.md): Manages message state and processing. +* [**Authentication Ecosystem**](./auth-ecosystem-at-1-0.md): Comprehensive wallet-less authentication (`~auth-hook@1.0`, `~secret@1.0`, `~cookie@1.0`, `~http-auth@1.0`). +* [**Data Discovery Engine**](./data-discovery-at-1-0.md): Advanced message search and query capabilities (`~query@1.0`). +* [**Data Replication Engine**](./data-replication-at-1-0.md): External data ingestion and synchronization (`~copycat@1.0`). * [`~patch@1.0`](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/exposing-process-state.html): Applies state updates directly to a process, often used for migrating or managing process data. ## Beyond the Basics Devices aren't limited to just computation or state management. They can represent more abstract concepts: -* **Security Devices** ([`~snp@1.0`](./source-code/dev_snp.md), [`dev_codec_httpsig`](./source-code/dev_codec_httpsig.md)): Handle tasks related to Trusted Execution Environments (TEEs) or message signing, adding layers of security and verification. +* **Security & Authentication Devices** ([`~snp@1.0`](./source-code/dev_snp.md), [`dev_codec_httpsig`](./source-code/dev_codec_httpsig.md), [**Authentication Ecosystem**](./auth-ecosystem-at-1-0.md)): Handle tasks related to Trusted Execution Environments (TEEs), message signing, wallet-less authentication, and session management, adding layers of security and verification. +* **Data Management Devices** ([**Data Discovery Engine**](./data-discovery-at-1-0.md), [**Data Replication Engine**](./data-replication-at-1-0.md)): Provide comprehensive data ingestion, search, and discovery capabilities for building data-rich applications with external source integration. * **Payment/Access Control Devices** ([`~p4@1.0`](./source-code/dev_p4.md), [`~faff@1.0`](./source-code/dev_faff.md)): Manage metering, billing, or access control for node services. * **Workflow/Utility Devices** ([`dev_cron`](./source-code/dev_cron.md), [`dev_stack`](./source-code/dev_stack.md), [`dev_monitor`](./source-code/dev_monitor.md)): Coordinate complex execution flows, schedule tasks, or monitor process activity. diff --git a/docs/build/devices/index.md b/docs/build/devices/index.md new file mode 100644 index 000000000..9676d4f69 --- /dev/null +++ b/docs/build/devices/index.md @@ -0,0 +1,171 @@ +# Core Devices + +HyperBEAM provides a comprehensive suite of devices that handle different aspects of computation, data management, authentication, and system operations. This page provides a complete overview of all available devices organized by their primary function. + +## Essential Core Devices + +These devices provide the fundamental building blocks for HyperBEAM applications: + +### **Process & State Management** + +- [**~process@1.0**](./process-at-1-0.md) - Manages persistent, shared computational states and orchestrates device execution +- [**~scheduler@1.0**](./scheduler-at-1-0.md) - Handles ordering and execution of messages within processes +- [**~meta@1.0**](./meta-at-1-0.md) - Configures node settings, hardware specs, and operational parameters + +### **Message & Data Handling** + +- [**~message@1.0**](./message-at-1-0.md) - Core message state and processing management +- [**~json@1.0**](./json-at-1-0.md) - Provides structured access to JSON data +- [**~relay@1.0**](./relay-at-1-0.md) - Forwards messages between AO nodes and external endpoints + +### **Execution Environments** + +- [**~wasm64@1.0**](./wasm64-at-1-0.md) - Executes WebAssembly code for high-performance computation +- [**~lua@5.3a**](./lua-at-5-3a.md) - Executes Lua scripts for flexible scripting capabilities + +## Device Ecosystems + +These comprehensive ecosystems provide advanced functionality through coordinated device interactions: + +### **Authentication & Security Ecosystem** +[**Authentication Ecosystem**](./auth-ecosystem-at-1-0.md) - Complete wallet-less authentication system + +**Included Devices:** + +- **~auth-hook@1.0** - Main authentication interceptor and request signer +- **~secret@1.0** - Wallet generation and secret management with access control +- **~cookie@1.0** - HTTP cookie-based session authentication +- **~http-auth@1.0** - HTTP Basic authentication with PBKDF2 key derivation + +**Key Capabilities:** + +- Zero-friction blockchain authentication +- Server-side wallet management +- Session persistence across requests +- Enterprise HTTP authentication +- Multi-signature wallet support + +### **Data Management Ecosystem** + +#### **Data Discovery Engine** +[**Data Discovery Engine**](./data-discovery-at-1-0.md) - Advanced message search and query system + +**Primary Device:** + +- **~query@1.0** - Flexible message discovery with multiple search modes and return formats + +**Key Capabilities:** + +- Complex message searching with flexible filtering +- GraphQL query support for advanced data operations +- Multiple return formats (paths, messages, counts, booleans) +- Integration with authentication for access-controlled queries + +#### **Data Replication Engine** +[**Data Replication Engine**](./data-replication-at-1-0.md) - External data ingestion and synchronization + +**Primary Device:** + +- **~copycat@1.0** - Orchestrates data replication from external sources + +**Key Capabilities:** + +- GraphQL endpoint data replication +- Direct Arweave node integration +- Automatic pagination and batch processing +- Comprehensive error handling and recovery + +## Security & TEE Devices + +Advanced security features and Trusted Execution Environment support: + +- [**~snp@1.0**](./source-code/dev_snp.md) - Secure Network Protocol for TEE operations +- [**dev_codec_httpsig**](./source-code/dev_codec_httpsig.md) - HTTP signature validation and processing + +## Payment & Access Control Devices + +Metering, billing, and access management: + +- [**~p4@1.0**](./source-code/dev_p4.md) - Payment processing and metering system +- [**~faff@1.0**](./source-code/dev_faff.md) - Fine-grained access control and permissions + +## Workflow & Utility Devices + +Process coordination and system utilities: + +- [**dev_cron**](./source-code/dev_cron.md) - Scheduled task execution and automation +- [**dev_stack**](./source-code/dev_stack.md) - Device stack management and coordination +- [**dev_monitor**](./source-code/dev_monitor.md) - System monitoring and health checks + +## Storage & Cache Devices + +Data persistence and caching infrastructure: + +- [**dev_cache**](./source-code/dev_cache.md) - Message caching and retrieval system +- [**hb_store**](./source-code/hb_store.md) - Persistent storage backend management + +## Communication & Network Devices + +Inter-node communication and network operations: + +- [**hb_gateway_client**](./source-code/hb_gateway_client.md) - Gateway communication client +- [**hb_http_client**](./source-code/hb_http_client.md) - HTTP client operations +- [**hb_http_server**](./source-code/hb_http_server.md) - HTTP server management + +## Development & Testing Devices + +Tools for development, testing, and debugging: + +- [**dev_test**](./source-code/dev_test.md) - Testing framework and utilities +- [**hb_debugger**](./source-code/hb_debugger.md) - Debugging tools and inspection +- [**dev_multipass**](./source-code/dev_multipass.md) - Multi-pass processing utilities + +## Legacy & Specialized Devices + +Specialized functionality and legacy support: + +- [**~patch@1.0**](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/exposing-process-state.html) - Direct state updates for process migration +- [**dev_wasi**](./source-code/dev_wasi.md) - WebAssembly System Interface support +- [**dev_poda**](./source-code/dev_poda.md) - Proof of Data Availability validation + +## Device Integration Patterns + +### **Complete Application Stack** +```text +Authentication → Data Replication → Data Discovery → Process Execution + ↓ ↓ ↓ ↓ + Auth Ecosystem Copycat Device Query Device Process Device +``` + +### **Data Workflow Integration** +1. **Ingestion:** Copycat replicates external data into local cache +2. **Discovery:** Query provides search and filtering over cached data +3. **Authentication:** Auth ecosystem controls access to data operations +4. **Processing:** Process devices utilize data for computation + +### **Security Integration** +- Authentication ecosystem provides transparent user authentication +- TEE devices enable secure computation environments +- Access control devices manage permissions and resource usage +- HTTP signature devices ensure message integrity + +## Getting Started + +### **For Authentication:** +Start with the [Authentication Ecosystem](./auth-ecosystem-at-1-0.md) to enable wallet-less blockchain applications. + +### **For Data Management:** +Begin with [Data Replication](./data-replication-at-1-0.md) to import external data, then use [Data Discovery](./data-discovery-at-1-0.md) for search and analysis. + +### **For Process Development:** +Review [~process@1.0](./process-at-1-0.md) for state management and [~scheduler@1.0](./scheduler-at-1-0.md) for message ordering. + +### **For Custom Devices:** +See [Building Devices](./building-devices.md) for guidance on creating your own devices. + +--- + +**Next Steps:** +- [Building Devices](./building-devices.md) - Learn to create custom devices +- [HyperBEAM Overview](./hyperbeam-devices.md) - Understand the device architecture +- [Source Code Reference](./source-code/) - Detailed technical documentation \ No newline at end of file From 9c47d4a311f0fa6c3cdb3a8727636eda51c24543 Mon Sep 17 00:00:00 2001 From: Dylan Shade <63427984+dpshade@users.noreply.github.com> Date: Mon, 15 Sep 2025 15:46:19 -0400 Subject: [PATCH 2/4] docs: refine device documentation for clarity and consistency - Updated the Authentication Ecosystem, Data Discovery Engine, and Data Replication Engine documentation for improved clarity and organization. - Enhanced descriptions and formatting for key functions and parameters across all devices. - Consolidated related sections and improved overall readability to facilitate better understanding of device interactions and capabilities. - Added links to related documentation for easier navigation within the HyperBEAM ecosystem. --- docs/build/devices/auth-ecosystem-at-1-0.md | 281 +++++++-------- docs/build/devices/data-discovery-at-1-0.md | 301 ++++++---------- docs/build/devices/data-replication-at-1-0.md | 336 ++++++++++-------- 3 files changed, 401 insertions(+), 517 deletions(-) diff --git a/docs/build/devices/auth-ecosystem-at-1-0.md b/docs/build/devices/auth-ecosystem-at-1-0.md index fee256ce2..0be372b5a 100644 --- a/docs/build/devices/auth-ecosystem-at-1-0.md +++ b/docs/build/devices/auth-ecosystem-at-1-0.md @@ -1,111 +1,82 @@ + # Device: Authentication Ecosystem (~auth-hook@1.0, ~secret@1.0, ~cookie@1.0, ~http-auth@1.0) ## Overview -The HyperBEAM Authentication Ecosystem provides a comprehensive suite of devices that enable wallet-less blockchain applications through server-side key management and transparent authentication. This ecosystem eliminates traditional blockchain UX friction by handling cryptographic operations transparently while maintaining security through trusted execution environments. +The Authentication Ecosystem in HyperBEAM provides a comprehensive suite of devices that enable wallet-less blockchain applications through server-side key management and transparent authentication. This ecosystem eliminates traditional blockchain user experience friction by handling cryptographic operations behind the scenes while maintaining security through trusted execution environments. -The ecosystem consists of four interconnected devices: +The ecosystem consists of four interconnected devices that work together to provide seamless authentication: -- **`~auth-hook@1.0`**: Main authentication interceptor and request signer -- **`~secret@1.0`**: Wallet generation and secret management -- **`~cookie@1.0`**: Session-based authentication via HTTP cookies -- **`~http-auth@1.0`**: HTTP Basic authentication with PBKDF2 key derivation +* **`~auth-hook@1.0`**: Primary authentication interceptor and request signer +* **`~secret@1.0`**: Manages wallet generation and secret storage +* **`~cookie@1.0`**: Provides session-based authentication via HTTP cookies +* **`~http-auth@1.0`**: Implements HTTP Basic authentication with PBKDF2 key derivation ## Core Concept: Zero-Friction Authentication -The authentication ecosystem transforms blockchain application UX from multi-step wallet connection processes into single-click experiences. Users interact with decentralized applications exactly like traditional web applications, while HyperBEAM handles all cryptographic operations server-side. +The authentication ecosystem transforms blockchain application user experience from multi-step wallet connection processes into single-click experiences. Users interact with decentralized applications in the same way they would with traditional web applications, while HyperBEAM handles all cryptographic operations server-side. ## Primary Device: ~auth-hook@1.0 -### Authentication Hook Overview The auth-hook device serves as the main entry point for wallet-less authentication, intercepting HTTP requests and automatically signing them with node-hosted wallets according to operator configuration. ### Key Functions -#### `request` -Processes incoming requests through a configured secret provider: -* **Action:** Intercepts HTTP requests containing the `&!` parameter -* **Process Flow:** - 1. Detect `&!` pattern in URL parameters - 2. Find and validate secret provider configuration - 3. Check relevance based on `when` conditions - 4. Generate or retrieve authentication secrets via provider - 5. Create wallet if needed through `~secret@1.0` - 6. Sign request and message sequences - 7. Finalize with provider-specific post-processing - -### Configuration Parameters - -#### Secret Provider Integration -```text -"secret-provider": { - "device": "cookie@1.0", - "generate-path": "generate", - "finalize-path": "finalize" -} -``` - -#### Activation Conditions -```text -"when": { - "committers": "uncommitted" | "always" | ["address1", "address2"], - "keys": "always" | ["authorization", "custom-header"] -} -``` +* **`request`** + * **Action:** Intercepts HTTP requests containing the `&!` parameter and processes them through a configured secret provider. + * **Process Flow:** Detects the `&!` pattern in URL parameters, finds and validates the secret provider configuration, checks relevance based on `when` conditions, generates or retrieves authentication secrets via the provider, creates wallets if needed through `~secret@1.0`, signs the request and message sequences, and finalizes with provider-specific post-processing. + * **Configuration Parameters:** + ``` + "secret-provider": { + "device": "cookie@1.0", + "generate-path": "generate", + "finalize-path": "finalize" + } + ``` + * **Activation Conditions:** + ``` + "when": { + "committers": "uncommitted" | "always" | ["address1", "address2"], + "keys": "always" | ["authorization", "custom-header"] + } + ``` ## Supporting Device: ~secret@1.0 -### Secret Management Overview The secret device manages wallet creation, storage, and commitment operations for node-hosted secrets with configurable access control and persistence modes. ### Key Functions -#### `generate` -Creates new wallets with authentication setup: +* **`generate`** + * **Action:** Creates new wallets with authentication setup. + * **Inputs:** `access-control`, `persist`, `controllers`, `required-controllers` + * **Persistence Modes:** + * `client`: Generated server-side, returned to client + * `in-memory`: Session-based storage + * `non-volatile`: Persistent disk storage -* **Parameters:** `access-control`, `persist`, `controllers`, `required-controllers` -* **Persistence Modes:** - - `client`: Generated server-side, returned to client - - `in-memory`: Session-based storage - - `non-volatile`: Persistent disk storage +* **`commit`** + * **Action:** Signs messages using hosted secrets. + * **Security Features:** Dual-layer security through access-control messages and controller verification, with support for multi-signature through required-controllers threshold. -#### `commit` -Signs messages using hosted secrets: - -* **Access Control:** Dual-layer security through access-control messages and controller verification -* **Multi-Signature:** Supports required-controllers threshold - -#### `export` / `sync` -Manages wallet portability and node synchronization: - -* **Export:** Access-controlled wallet extraction -* **Sync:** Cross-node wallet synchronization - -### Integration with Auth-Hook - -1. Auth-hook generates/retrieves secrets via provider -2. Passes secrets to `~secret@1.0` for wallet operations -3. Uses generated wallets for request signing -4. Maintains session consistency through provider +* **`export` / `sync`** + * **Action:** Manages wallet portability and node synchronization. + * **Features:** Access-controlled wallet extraction and cross-node wallet synchronization. ## Provider Device: ~cookie@1.0 -### Cookie Authentication Overview -Manages HTTP cookie-based authentication and session persistence, implementing the generator interface for auth-hook integration. +The cookie device manages HTTP cookie-based authentication and session persistence, implementing the generator interface for auth-hook integration. ### Key Functions -#### Generator Interface Implementation -```text -generate: Creates or retrieves authentication secrets from cookies -finalize: Adds set-cookie headers to response sequences -``` - -#### Cookie Management +* **Generator Interface Implementation** + * **`generate`**: Creates or retrieves authentication secrets from cookies + * **`finalize`**: Adds set-cookie headers to response sequences -* **Formats:** set-cookie (full attributes), cookie (simple), structured-fields (internal) -* **Security:** HMAC-SHA256 commitments, HTTPOnly, Secure, SameSite support -* **Storage:** `wallet-
` and `secret-` cookie patterns +* **Cookie Management** + * **Formats:** set-cookie (full attributes), cookie (simple), structured-fields (internal) + * **Security:** HMAC-SHA256 commitments, HTTPOnly, Secure, SameSite support + * **Storage:** `wallet-
` and `secret-` cookie patterns ### Session Flow @@ -115,19 +86,17 @@ finalize: Adds set-cookie headers to response sequences ## Provider Device: ~http-auth@1.0 -### HTTP Authentication Overview -Implements HTTP Basic authentication with PBKDF2 key derivation, providing enterprise-grade authentication for protected resources. +The http-auth device implements HTTP Basic authentication with PBKDF2 key derivation, providing enterprise-grade authentication for protected resources. ### Key Functions -#### `generate` -Processes HTTP Authorization headers: - -* **PBKDF2 Parameters:** 1,200,000 iterations, SHA256, 64-byte keys -* **Security:** 2x OWASP recommendation, ~5-10 derivations/second -* **401 Response:** Triggers browser authentication prompts +* **`generate`** + * **Action:** Processes HTTP Authorization headers. + * **PBKDF2 Parameters:** 1,200,000 iterations, SHA256, 64-byte keys (2x OWASP recommendation) + * **Performance:** ~5-10 derivations/second + * **Response:** Returns 401 with WWW-Authenticate header when no credentials are provided -#### Authentication Flow +### Authentication Flow 1. **No Credentials:** Return 401 with WWW-Authenticate header 2. **Basic Auth:** Extract and decode Authorization header @@ -137,7 +106,9 @@ Processes HTTP Authorization headers: ## Device Integration & Synergy ### Complete Authentication Workflow -```text + +The authentication process follows this sequence: +``` HTTP Request → Auth-Hook → Provider (Cookie/HTTP-Auth) → Secret → Wallet → Signed Response ↓ ↓ ↓ ↓ ↓ ↓ &! Parameter Intercept Generate Secret Create Key Sign Msg Set Cookie @@ -145,92 +116,83 @@ HTTP Request → Auth-Hook → Provider (Cookie/HTTP-Auth) → Secret → Wallet ### Integration with Core Devices -#### With Process Device (`~process@1.0`) +The Authentication Ecosystem integrates with other HyperBEAM devices: -- Automatic signing of process communications -- Seamless AO process interaction without wallet setup -- Transparent message commitment in ANS-104 format - -#### With Query Device (`~query@1.0`) -- Authenticated data discovery and search -- User-specific query results based on wallet identity -- Access-controlled message retrieval - -#### With Copycat Device (`~copycat@1.0`) -- Authenticated data replication from external sources -- Signed import operations for data integrity -- Identity-based data synchronization - -#### With Meta Device (`~meta@1.0`) -- Node configuration for authentication providers -- Access control policy management -- Resource allocation for auth operations +* **With Process Device (`~process@1.0`)**: Automatic signing of process communications, seamless AO process interaction without wallet setup +* **With Query Device (`~query@1.0`)**: Authenticated data discovery and search, user-specific query results +* **With Copycat Device (`~copycat@1.0`)**: Authenticated data replication from external sources +* **With Meta Device (`~meta@1.0`)**: Node configuration for authentication providers, access control policy management ### Cross-Device Authentication Patterns -#### Multi-Provider Support -```text -"on": { - "request": [ - { - "device": "auth-hook@1.0", - "secret-provider": {"device": "cookie@1.0"} - }, - { - "device": "auth-hook@1.0", - "secret-provider": {"device": "http-auth@1.0"}, - "when": {"keys": ["authorization"]} - } - ] -} -``` - -#### Chained Authentication -```text -Cookie Auth → HTTP Auth → Secret Management → Process Interaction - ↓ ↓ ↓ ↓ - Session Enterprise Wallet Creation Signed Messages -``` +* **Multi-Provider Support** + ``` + "on": { + "request": [ + { + "device": "auth-hook@1.0", + "secret-provider": {"device": "cookie@1.0"} + }, + { + "device": "auth-hook@1.0", + "secret-provider": {"device": "http-auth@1.0"}, + "when": {"keys": ["authorization"]} + } + ] + } + ``` + +* **Chained Authentication** + ``` + Cookie Auth → HTTP Auth → Secret Management → Process Interaction + ↓ ↓ ↓ ↓ + Session Enterprise Wallet Creation Signed Messages + ``` ## Security Architecture ### Trust Model -- **Server-Trust:** Users trust HyperBEAM nodes for key management -- **TEE Integration:** Designed for Trusted Execution Environments -- **Cryptographic Auditability:** All operations create verifiable signatures -- **Key Isolation:** Private keys never leave server memory + +* **Server-Trust:** Users trust HyperBEAM nodes for key management +* **TEE Integration:** Designed for Trusted Execution Environments +* **Cryptographic Auditability:** All operations create verifiable signatures +* **Key Isolation:** Private keys never leave server memory ### Multi-Layer Security + 1. **Provider Layer:** Cookie/HTTP authentication 2. **Access Control:** Configurable access-control messages 3. **Controller Verification:** Multi-signature support 4. **Request Signing:** RSA-PSS/HMAC cryptographic proofs ### Security Best Practices -- HTTPS-only deployment -- Secure cookie attributes (HTTPOnly, Secure, SameSite) -- Strong PBKDF2 parameters -- Regular session key rotation -- Comprehensive audit logging + +* HTTPS-only deployment +* Secure cookie attributes (HTTPOnly, Secure, SameSite) +* Strong PBKDF2 parameters +* Regular session key rotation +* Comprehensive audit logging ## Performance Considerations ### Optimization Strategies -- **In-Memory Caching:** Active wallet cache for sessions -- **Lazy Loading:** On-demand wallet retrieval from storage -- **Batch Operations:** Parallel message signing -- **Session Reuse:** Authentication state persistence + +* **In-Memory Caching:** Active wallet cache for sessions +* **Lazy Loading:** On-demand wallet retrieval from storage +* **Batch Operations:** Parallel message signing +* **Session Reuse:** Authentication state persistence ### Scalability Metrics -- **Memory:** ~2KB per active session (in-memory mode) -- **Computation:** RSA signing ~5ms, HMAC ~0.1ms per operation -- **Throughput:** ~10K concurrent sessions per GB RAM -- **Cookie Limits:** 4KB browser limit for session data + +* **Memory:** ~2KB per active session (in-memory mode) +* **Computation:** RSA signing ~5ms, HMAC ~0.1ms per operation +* **Throughput:** ~10K concurrent sessions per GB RAM +* **Cookie Limits:** 4KB browser limit for session data ## Implementation Examples ### Basic Cookie Authentication -```text +``` "on": { "request": { "device": "auth-hook@1.0", @@ -240,7 +202,7 @@ Cookie Auth → HTTP Auth → Secret Management → Process Interaction ``` ### Enterprise HTTP Authentication -```text +``` "on": { "request": { "device": "auth-hook@1.0", @@ -254,7 +216,7 @@ Cookie Auth → HTTP Auth → Secret Management → Process Interaction ``` ### Multi-Signature Wallet Management -```text +``` "secret-provider": { "device": "cookie@1.0", "access-control": { @@ -268,18 +230,15 @@ Cookie Auth → HTTP Auth → Secret Management → Process Interaction ## Error Handling & Recovery ### Graceful Degradation -- Skip authentication if provider not found -- Return original request if relevance conditions not met -- Detailed error logging with context preservation -- Partial failure isolation in batch operations + +* Skip authentication if provider not found +* Return original request if relevance conditions not met +* Detailed error logging with context preservation +* Partial failure isolation in batch operations ### Monitoring & Debugging -- Event-driven logging across all devices -- Performance metrics for auth operations -- Session tracking and analytics -- Security audit trail maintenance - -**Related Documentation:** -- [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture -- [Building Devices](./building-devices.md) - Creating custom devices -- [Core Devices Index](./index.md) - Complete device catalog \ No newline at end of file + +* Event-driven logging across all devices +* Performance metrics for auth operations +* Session tracking and analytics +* Security audit trail maintenance diff --git a/docs/build/devices/data-discovery-at-1-0.md b/docs/build/devices/data-discovery-at-1-0.md index 7fdde3059..b38e7b9e6 100644 --- a/docs/build/devices/data-discovery-at-1-0.md +++ b/docs/build/devices/data-discovery-at-1-0.md @@ -1,147 +1,111 @@ -# Device: Data Discovery Engine (~query@1.0) + +# Device: ~query@1.0 ## Overview -The `~query@1.0` device serves as HyperBEAM's primary data discovery engine, providing flexible search capabilities over cached messages with multiple matching modes and return formats. It enables efficient data retrieval, supports GraphQL queries, and integrates seamlessly with the broader HyperBEAM ecosystem for comprehensive data workflows. +The [`~query@1.0`](./source-code/dev_query.md) device serves as HyperBEAM's primary data discovery engine, providing flexible search capabilities over cached messages. It enables efficient data retrieval with multiple matching modes and return formats. -This device is essential for: +This device is useful for: -- Searching cached messages by key-value pairs with flexible filtering -- Supporting various query modes and return formats for different use cases -- Providing GraphQL query capabilities for complex data operations -- Enabling efficient data discovery in conjunction with replication systems +* Searching cached messages by key-value pairs with flexible filtering +* Supporting various query modes for different use cases +* Providing GraphQL query capabilities for complex data operations +* Enabling efficient data discovery in conjunction with replication systems ## Core Concept: Message Discovery -The query device operates as a sophisticated search interface over a node's cached messages, supporting various matching strategies and flexible return formats. It can search by specific keys, all message fields, or custom specifications with configurable filtering and exclusion rules, making it the central hub for data discovery in HyperBEAM applications. +The query device operates as a search interface over a node's cached messages, supporting various matching strategies and flexible return formats. It can search by specific keys, all message fields, or custom specifications with configurable filtering and exclusion rules, making it the central hub for data discovery in HyperBEAM applications. ## Key Functions (Keys) ### `all` -Searches for all keys and values in the request message against cached data. -* **`GET /~query@1.0/all`** - * **Action:** Matches all keys in the request against cached messages - * **Parameters:** - * `exclude`: List of keys to exclude from search (default: ["path", "commitments", "return", "exclude", "only"]) - * `return`: Return format specification (paths, messages, count, first-path, first-message, boolean) - * **Response:** Query results in specified format +* **`GET /~query@1.0/all`** + * **Action:** Matches all keys in the request against cached messages. + * **Inputs:** + * `exclude`: List of keys to exclude from search (default: ["path", "commitments", "return", "exclude", "only"]) + * `return`: Return format specification (paths, messages, count, first-path, first-message, boolean) + * **Response:** Query results in the specified format. ### `base` -Searches for all keys and values in the base message. -* **`GET /~query@1.0/base`** - * **Action:** Matches all keys in the base message against cached messages - * **Usage:** Useful when query parameters are pre-configured in the base message - * **Response:** Query results based on base message keys +* **`GET /~query@1.0/base`** + * **Action:** Matches all keys in the base message against cached messages. + * **Response:** Query results based on base message keys. + * This is useful when query parameters are pre-configured in the base message. ### `only` -Searches for specific keys specified in the request. -* **`GET /~query@1.0/only`** - * **Parameters:** - * `only`: Key specification in multiple formats: - * Binary: Comma-separated key names ("key1,key2,key3") - * Map: Direct match specification {"key": "value"} - * List: Array of keys to extract from request/base - * **Response:** Results matching only specified keys +* **`GET /~query@1.0/only`** + * **Action:** Searches for specific keys specified in the request. + * **Inputs:** + * `only`: Key specification in multiple formats: + * Binary: Comma-separated key names ("key1,key2,key3") + * Map: Direct match specification {"key": "value"} + * List: Array of keys to extract from request/base + * **Response:** Results matching only specified keys. ### `graphql` -Executes GraphQL queries against the node's data. -* **`POST /~query@1.0/graphql`** - * **Action:** Processes GraphQL queries for advanced data retrieval - * **Integration:** Delegates to `dev_query_graphql` module - * **Request Body:** GraphQL query with variables and operation names - * **Response:** GraphQL-formatted results with schema validation +* **`POST /~query@1.0/graphql`** + * **Action:** Processes GraphQL queries for advanced data retrieval. + * **Inputs:** GraphQL query with variables and operation names in the request body. + * **Response:** GraphQL-formatted results with schema validation. + * Delegates to the `dev_query_graphql` module for processing. ### `has_results` -Determines if a GraphQL response contains transaction results. -* **`GET /~query@1.0/has_results`** - * **Action:** Validates GraphQL responses for gateway client configuration - * **Usage:** Enables HyperBEAM's multirequest configuration - * **Response:** Boolean indicating presence of results +* **`GET /~query@1.0/has_results`** + * **Action:** Determines if a GraphQL response contains transaction results. + * **Response:** Boolean indicating presence of results. + * Enables HyperBEAM's multirequest configuration for gateway clients. ## Return Format Specifications -### `paths` (Default) -Returns list of message identifiers for efficient reference: -```text -{"return": "paths"} -// Response: ["msg_id_1", "msg_id_2", "msg_id_3"] -``` +The `return` parameter controls the format of query results: -### `messages` -Returns complete message objects for detailed analysis: -```text -{"return": "messages"} -// Response: [complete_message_1, complete_message_2, ...] -``` - -### `count` -Returns numerical count of matches for analytics: -```text -{"return": "count"} -// Response: 42 -``` - -### `first-path` / `first-message` -Returns first match for single-result queries: -```text -{"return": "first-message"} -// Response: {first_matching_message} -``` - -### `boolean` -Returns existence check for conditional logic: -```text -{"return": "boolean"} -// Response: true -``` +* **`paths`** (Default): Returns list of message identifiers for efficient reference. + ``` + {"return": "paths"} + // Response: ["msg_id_1", "msg_id_2", "msg_id_3"] + ``` -## Core Dependencies & Architecture +* **`messages`**: Returns complete message objects for detailed analysis. + ``` + {"return": "messages"} + // Response: [complete_message_1, complete_message_2, ...] + ``` -### Cache Layer (`~cache@1.0`) -Primary data source providing: -- Indexed access to stored messages -- Match functionality for key-value searches -- Message loading and serialization management -- Performance optimization through caching strategies +* **`count`**: Returns numerical count of matches for analytics. + ``` + {"return": "count"} + // Response: 42 + ``` -### Storage Layer (`~store@1.0`) -Underlying persistent storage: -- Houses actual message data with durability guarantees -- Supports various storage backends (LMDB, RocksDB) -- Provides indexing capabilities for efficient queries -- Manages storage partitioning and conflict resolution +* **`first-path`** / **`first-message`**: Returns first match for single-result queries. + ``` + {"return": "first-message"} + // Response: {first_matching_message} + ``` -### Message Processing (`~message@1.0`) -Message format handling: -- Validates message structure and format compliance -- Handles commitment and signature processing -- Manages message serialization across different formats -- Ensures data integrity during query operations +* **`boolean`**: Returns existence check for conditional logic. + ``` + {"return": "boolean"} + // Response: true + ``` -## Device Integration & Synergy +## Device Integration ### With Copycat Device (`~copycat@1.0`) -Comprehensive data lifecycle management: -**Data Pipeline:** -```text -External Source → Copycat → Cache → Query → Application - ↓ ↓ ↓ ↓ ↓ - Remote Data Replication Storage Discovery Usage -``` +The query device works seamlessly with the copycat device to enable comprehensive data lifecycle management: -**Workflow Integration:** 1. **Replication Phase:** Copycat imports external data into local cache 2. **Discovery Phase:** Query provides search and discovery over imported data 3. **Application Phase:** Combined pattern enables offline-first applications with complete datasets **Example Workflow:** -```text +``` // First: Replicate data from external source POST /~copycat@1.0/graphql { @@ -157,29 +121,11 @@ GET /~query@1.0/all } ``` -### With Authentication Ecosystem -Authenticated and access-controlled queries: +### With Process Device (`~process@1.0`) -**Protected Data Discovery:** -- Query operations can be protected by `~auth-hook@1.0` -- Enables user-specific data discovery based on wallet identity -- Supports access-controlled search patterns with fine-grained permissions +The query device can be used for process state discovery and analysis: -**Identity-Based Queries:** -```text -GET /~query@1.0/all -Authorization: Bearer -{ - "owner": "", - "return": "messages" -} ``` - -### With Process Device (`~process@1.0`) -Process state discovery and analysis: - -**Process Message Discovery:** -```text GET /~query@1.0/all { "action": "get-messages", @@ -187,22 +133,17 @@ GET /~query@1.0/all } ``` -**Historical Analysis:** -- Query process message sequences for state reconstruction -- Analyze process evolution over time -- Support process debugging and audit workflows - -### With Meta Device (`~meta@1.0`) -Node configuration and resource management: -- Query device configuration through meta device -- Resource allocation for query operations -- Performance monitoring and optimization +This enables: +* Query process message sequences for state reconstruction +* Analysis of process evolution over time +* Support for process debugging and audit workflows ## Advanced Query Patterns ### Multi-Key Filtering + All specified keys must match (AND logic): -```text +``` { "type": "message", "device": "process@1.0", @@ -212,8 +153,9 @@ All specified keys must match (AND logic): ``` ### Nested Message Support + Search within nested message structures: -```text +``` { "nested.field": "value", "complex.path.data": "target", @@ -222,8 +164,9 @@ Search within nested message structures: ``` ### Exclusion-Based Queries + Filter out unwanted data during search: -```text +``` { "type": "message", "exclude": ["internal-timestamp", "debug-info", "system-metadata"], @@ -231,75 +174,33 @@ Filter out unwanted data during search: } ``` -### Key Priority Resolution -When using key lists in `only` mode: -1. Search in request message first -2. Fall back to base message if not found -3. Filter out `not_found` values automatically -4. Maintain search order for result consistency - ## Performance Optimization -### Caching Strategy -- **Index Utilization:** Leverages underlying store's native indexing capabilities -- **Memory Efficiency:** Returns paths by default to minimize memory usage -- **Lazy Loading:** Full messages loaded only when explicitly requested -- **Query Result Caching:** Frequently accessed queries cached for improved performance - -### Search Optimization -- **Filtered Matching:** Excludes metadata keys by default for focused searches -- **Batch Processing:** Supports bulk query operations for improved throughput -- **Parallel Processing:** Multiple queries can be processed concurrently -- **Resource Management:** Configurable limits prevent resource exhaustion - -## GraphQL Integration - -### Advanced Query Processing -The GraphQL integration provides: -- **Schema Validation:** Ensures query structure compliance -- **Variable Substitution:** Dynamic query parameterization -- **Result Formatting:** Standardized GraphQL response format -- **Error Handling:** Comprehensive error reporting and recovery - -### Gateway Client Support -The `has_results` function enables: -- **Response Validation:** Ensures query completeness across multiple nodes -- **Multirequest Configuration:** Supports distributed query coordination -- **Result Admissibility:** Determines acceptable response criteria -- **Consensus Building:** Enables distributed data discovery patterns - -## Security Considerations +The query device implements several optimization strategies: -### Access Control -- **Cache Access:** Queries operate within node's security context -- **Key Filtering:** Sensitive keys excluded by default from search results -- **Resource Limits:** Underlying cache implements query limits and rate limiting -- **Authentication Integration:** Subject to node's access control policies +* **Index Utilization:** Leverages underlying store's native indexing capabilities +* **Memory Efficiency:** Returns paths by default to minimize memory usage +* **Lazy Loading:** Full messages loaded only when explicitly requested +* **Query Result Caching:** Frequently accessed queries cached for improved performance -### Data Privacy -- **Selective Exposure:** Configurable key exclusion for privacy protection -- **Audit Logging:** Query operations logged for security monitoring -- **Permission Enforcement:** Integration with authentication ecosystem -- **Secure Defaults:** Conservative security settings by default +## Security Considerations -## Error Handling & Recovery +* **Cache Access:** Queries operate within node's security context +* **Key Filtering:** Sensitive keys excluded by default from search results +* **Resource Limits:** Underlying cache implements query limits and rate limiting +* **Authentication Integration:** Subject to node's access control policies -### Graceful Degradation -- **Not Found:** Returns appropriate error codes or empty results based on return type -- **Invalid Specifications:** Clear error messages for malformed queries -- **Resource Exhaustion:** Graceful handling of resource limits -- **Partial Failures:** Robust error isolation in complex queries +## Error Handling -### Monitoring & Debugging -- **Query Analytics:** Performance metrics and usage statistics -- **Error Tracking:** Comprehensive error logging with context -- **Performance Monitoring:** Query execution time and resource usage tracking -- **Debug Support:** Detailed logging for development and troubleshooting +* **Not Found:** Returns appropriate error codes or empty results based on return type +* **Invalid Specifications:** Clear error messages for malformed queries +* **Resource Exhaustion:** Graceful handling of resource limits +* **Partial Failures:** Robust error isolation in complex queries ## Implementation Examples ### Basic Message Discovery -```text +``` GET /~query@1.0/all { "device": "process@1.0", @@ -309,7 +210,7 @@ GET /~query@1.0/all ``` ### Complex Filtered Search -```text +``` GET /~query@1.0/only { "only": "owner,type,timestamp", @@ -320,7 +221,7 @@ GET /~query@1.0/only ``` ### GraphQL Query -```text +``` POST /~query@1.0/graphql { "query": "query GetProcessMessages($processId: String!) { @@ -332,9 +233,11 @@ POST /~query@1.0/graphql } ``` ---- +## See Also + +- [`~cache@1.0`](./source-code/dev_cache.md) - Primary data source for query operations +- [`~store@1.0`](./source-code/dev_store.md) - Underlying persistent storage +- [`~message@1.0`](./source-code/dev_message.md) - Message format handling +- [`~copycat@1.0`](./source-code/dev_copycat.md) - Data replication device -**Related Documentation:** -- [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture -- [Building Devices](./building-devices.md) - Creating custom devices -- [Core Devices Index](./index.md) - Complete device catalog \ No newline at end of file +[query module](./source-code/dev_query.md) diff --git a/docs/build/devices/data-replication-at-1-0.md b/docs/build/devices/data-replication-at-1-0.md index 481cb23c4..c6722e2d7 100644 --- a/docs/build/devices/data-replication-at-1-0.md +++ b/docs/build/devices/data-replication-at-1-0.md @@ -1,81 +1,82 @@ -# Device: Data Replication Engine (~copycat@1.0) + +# Device: ~copycat@1.0 ## Overview -The `~copycat@1.0` device orchestrates comprehensive data replication from external sources into HyperBEAM node caches. It serves as the primary data ingestion engine, supporting multiple replication strategies and sources while providing robust error handling, pagination management, and integration with the broader HyperBEAM ecosystem. +The [`~copycat@1.0`](./source-code/dev_copycat.md) device orchestrates comprehensive data replication from external sources into HyperBEAM node caches. It serves as the primary data ingestion engine, supporting multiple replication strategies and sources while providing robust error handling, pagination management, and integration with the broader HyperBEAM ecosystem. This device is essential for: -- Replicating messages from remote Arweave networks and GraphQL endpoints -- Building comprehensive local datasets for offline-first applications -- Enabling high-performance data access through local caching -- Supporting incremental and full data synchronization workflows +* Replicating messages from remote Arweave networks and GraphQL endpoints +* Building comprehensive local datasets for offline-first applications +* Enabling high-performance data access through local caching +* Supporting incremental and full data synchronization workflows ## Core Concept: Data Ingestion Orchestration -The copycat device acts as a sophisticated data ingestion orchestrator that fetches messages from various external sources and imports them into the local node's cache system. It supports multiple engines for different data sources, handles complex pagination scenarios, and provides comprehensive error recovery during large-scale replication operations. +The `~copycat@1.0` device acts as a sophisticated data ingestion orchestrator that fetches messages from various external sources and imports them into the local node's cache system. It supports multiple engines for different data sources, handles complex pagination scenarios, and provides comprehensive error recovery during large-scale replication operations. ## Key Functions (Keys) ### `graphql` -Fetches data from GraphQL endpoints for comprehensive replication. - -* **`POST /~copycat@1.0/graphql`** - * **Action:** Queries remote GraphQL endpoints and systematically indexes results locally - * **Parameters:** - * `query`: GraphQL query string or structured query specification - * `variables`: GraphQL query variables for parameterized queries - * `operationName`: Specific operation to execute in multi-operation queries - * `node`: Target GraphQL endpoint URL for data source - * **Processing:** Automatic pagination handling, message parsing, and cache integration - * **Response:** Total number of successfully indexed messages with batch statistics + +* **`POST /~copycat@1.0/graphql`** + * **Action:** Queries remote GraphQL endpoints and systematically indexes results locally. + * **Inputs:** + * `query`: GraphQL query string or structured query specification + * `variables`: GraphQL query variables for parameterized queries + * `operationName`: Specific operation to execute in multi-operation queries + * `node`: Target GraphQL endpoint URL for data source + * **Response:** Total number of successfully indexed messages with batch statistics. + * **Processing:** Automatic pagination handling, message parsing, and cache integration. ### `arweave` -Fetches data directly from Arweave nodes for block-level replication. - -* **`POST /~copycat@1.0/arweave`** - * **Action:** Connects directly to Arweave nodes and imports transaction/block data - * **Parameters:** - * `node`: Target Arweave node URL - * `from`: Starting block height for replication - * `to`: Ending block height for replication range - * `filter`: Transaction filtering criteria - * **Integration:** Uses `~arweave@2.9-pre` device for native Arweave communication - * **Response:** Replication status with imported message count and range coverage + +* **`POST /~copycat@1.0/arweave`** + * **Action:** Connects directly to Arweave nodes and imports transaction/block data. + * **Inputs:** + * `node`: Target Arweave node URL + * `from`: Starting block height for replication + * `to`: Ending block height for replication range + * `filter`: Transaction filtering criteria + * **Response:** Replication status with imported message count and range coverage. + * **Integration:** Uses `~arweave@2.9-pre` device for native Arweave communication. ## Supported Data Sources & Engines ### GraphQL Endpoints -**Comprehensive Gateway Support:** -- Arweave Gateway GraphQL APIs (arweave.net, ar.io gateways) -- Custom GraphQL services and federated endpoints -- Multi-endpoint coordination for redundancy and performance +The device provides comprehensive gateway support for: -**Query Generation Capabilities:** +* Arweave Gateway GraphQL APIs (arweave.net, ar.io gateways) +* Custom GraphQL services and federated endpoints +* Multi-endpoint coordination for redundancy and performance -- Automatic query construction from filter parameters -- Custom GraphQL query support with variable interpolation -- Template-based query generation for common patterns +Query generation capabilities include: + +* Automatic query construction from filter parameters +* Custom GraphQL query support with variable interpolation +* Template-based query generation for common patterns ### Arweave Nodes -**Direct Node Integration:** -- Block-level data replication with height-based ranges -- Transaction indexing and comprehensive metadata capture -- Built-in caching mechanisms to prevent duplicate fetches -- Reverse chronological processing (latest to genesis) +Direct node integration features: + +* Block-level data replication with height-based ranges +* Transaction indexing and comprehensive metadata capture +* Built-in caching mechanisms to prevent duplicate fetches +* Reverse chronological processing (latest to genesis) -**Performance Optimization:** +Performance optimization includes: -- Utilizes `~arweave@2.9-pre` device's native caching -- Efficient block processing with conflict detection -- Resource-aware processing for large-scale replication +* Utilization of `~arweave@2.9-pre` device's native caching +* Efficient block processing with conflict detection +* Resource-aware processing for large-scale replication ## Filter Types & Query Patterns ### Tag-Based Filtering -Precise content filtering based on Arweave tags: + ```text { "tag": "Content-Type", @@ -84,7 +85,7 @@ Precise content filtering based on Arweave tags: ``` ### Owner-Based Filtering -User-specific data replication: + ```text { "owner": "wallet-address-here" @@ -92,7 +93,7 @@ User-specific data replication: ``` ### Recipient-Based Filtering -Target-specific message replication: + ```text { "recipient": "target-address-here" @@ -100,7 +101,7 @@ Target-specific message replication: ``` ### Multi-Tag Complex Filtering -Advanced filtering with multiple criteria: + ```text { "tags": { @@ -112,7 +113,7 @@ Advanced filtering with multiple criteria: ``` ### Comprehensive Replication -Complete dataset mirroring: + ```text { "all": true, @@ -123,7 +124,8 @@ Complete dataset mirroring: ## Data Processing Pipeline ### Message Parsing & Validation -**Robust Data Processing:** + +The device implements robust data processing: 1. **Result Processing:** Converts GraphQL responses to HyperBEAM message format 2. **Structure Validation:** Ensures message format compliance and integrity @@ -131,7 +133,8 @@ Complete dataset mirroring: 4. **Format Conversion:** Handles various input formats and standardizes output ### Cache Integration & Storage -**Seamless Storage Integration:** + +Seamless storage integration includes: 1. **Write Operations:** Efficiently stores parsed messages in node cache 2. **Conflict Resolution:** Handles duplicate message scenarios intelligently @@ -139,7 +142,9 @@ Complete dataset mirroring: 4. **Transaction Safety:** Ensures data consistency during batch operations ### Pagination & Batch Management -**Scalable Data Handling:** + +The device implements scalable data handling with this workflow: + ```text Fetch Batch → Parse Messages → Validate Format → Write to Cache → Update Progress ↓ ↓ ↓ ↓ ↓ @@ -147,48 +152,52 @@ Fetch Batch → Parse Messages → Validate Format → Write to Cache → Update Response Parsing Validation Integration Tracking ``` -**Automatic Pagination:** -- Cursor-based pagination with seamless continuation -- Configurable batch sizes for optimal performance -- Progress tracking and resumption capabilities -- Memory-efficient streaming processing +Automatic pagination features include: +* Cursor-based pagination with seamless continuation +* Configurable batch sizes for optimal performance +* Progress tracking and resumption capabilities +* Memory-efficient streaming processing ## Core Dependencies & Architecture ### Gateway Client (`~gateway-client@1.0`) -**Remote Communication Engine:** -- GraphQL endpoint access and communication management -- Result parsing and protocol-specific data conversion -- Multi-endpoint federation and load balancing -- Response validation and comprehensive error handling + +Remote communication engine providing: +* GraphQL endpoint access and communication management +* Result parsing and protocol-specific data conversion +* Multi-endpoint federation and load balancing +* Response validation and comprehensive error handling ### Arweave Integration (`~arweave@2.9-pre`) -**Native Arweave Communication:** -- Direct Arweave node communication for block data -- Transaction indexing with built-in caching mechanisms -- Height-based range queries for efficient replication -- Conflict detection and resolution for duplicate data + +Native Arweave communication features: +* Direct Arweave node communication for block data +* Transaction indexing with built-in caching mechanisms +* Height-based range queries for efficient replication +* Conflict detection and resolution for duplicate data ### Cache Layer (`~cache@1.0`) -**Primary Replication Target:** -- Central storage for all imported messages -- Indexing infrastructure for imported data -- Message validation and integrity checking during import -- Storage conflict management and deduplication + +Primary replication target providing: +* Central storage for all imported messages +* Indexing infrastructure for imported data +* Message validation and integrity checking during import +* Storage conflict management and deduplication ### Message Processing (`~message@1.0`) -**Format Standardization:** -- Converts external formats to HyperBEAM message standards -- Validates message structure before caching operations -- Handles commitment and signature processing for authenticated messages -- Manages serialization compatibility across different sources + +Format standardization features: +* Converts external formats to HyperBEAM message standards +* Validates message structure before caching operations +* Handles commitment and signature processing for authenticated messages +* Manages serialization compatibility across different sources ## Device Integration & Synergy ### With Query Device (`~query@1.0`) -**Complete Data Lifecycle Management:** -**Integrated Workflow:** +Complete data lifecycle management with integrated workflow: + ```text 1. Replication: Copycat → Cache (import external data) 2. Discovery: Query → Cache (search replicated content) @@ -196,6 +205,7 @@ Fetch Batch → Parse Messages → Validate Format → Write to Cache → Update ``` **Example Integration:** + ```text // Phase 1: Replicate application data POST /~copycat@1.0/graphql @@ -222,14 +232,14 @@ GET /~query@1.0/only ``` ### With Authentication Ecosystem -**Authenticated Replication Operations:** -**Identity-Based Replication:** -- Replicate user-specific data based on authenticated wallet identity -- Signed import operations for data integrity verification -- Access-controlled replication with fine-grained permissions +Identity-based replication features: +* Replicate user-specific data based on authenticated wallet identity +* Signed import operations for data integrity verification +* Access-controlled replication with fine-grained permissions **Multi-User Data Management:** + ```text // Authenticated replication request POST /~copycat@1.0/graphql @@ -241,14 +251,14 @@ Authorization: Bearer ``` ### With Process Device (`~process@1.0`) -**Process History Replication:** -**Complete Process Reconstruction:** -- Import complete process message sequences for historical analysis -- Build offline process state snapshots for performance optimization -- Enable comprehensive process debugging and audit capabilities +Complete process reconstruction capabilities: +* Import complete process message sequences for historical analysis +* Build offline process state snapshots for performance optimization +* Enable comprehensive process debugging and audit capabilities **Process-Specific Replication:** + ```text POST /~copycat@1.0/graphql { @@ -261,9 +271,9 @@ POST /~copycat@1.0/graphql ``` ### With Scheduler Device (`~scheduler@1.0`) -**Automated Replication Workflows:** -**Scheduled Data Synchronization:** +Scheduled data synchronization example: + ```text { "device": "scheduler@1.0", @@ -277,20 +287,20 @@ POST /~copycat@1.0/graphql } ``` -**Continuous Integration Patterns:** -- Incremental updates for active datasets -- Full synchronization for periodic consistency checks -- Error recovery and retry mechanisms for failed operations +Continuous integration patterns include: +* Incremental updates for active datasets +* Full synchronization for periodic consistency checks +* Error recovery and retry mechanisms for failed operations ### With Meta Device (`~meta@1.0`) -**Node Configuration Integration:** -**Endpoint Management:** -- Replication endpoint configuration and credential management -- Resource allocation and performance tuning for replication operations -- Access control policy enforcement for external data sources +Endpoint management features: +* Replication endpoint configuration and credential management +* Resource allocation and performance tuning for replication operations +* Access control policy enforcement for external data sources **Resource Optimization:** + ```text { "replication-config": { @@ -305,44 +315,48 @@ POST /~copycat@1.0/graphql ## Error Handling & Recovery ### Comprehensive Error Management -**Multi-Level Error Handling:** + +Multi-level error handling includes: **Parse Failures:** -- Individual message parse errors logged with detailed context -- Batch processing continues despite individual message failures -- Comprehensive error reporting for debugging and monitoring +* Individual message parse errors logged with detailed context +* Batch processing continues despite individual message failures +* Comprehensive error reporting for debugging and monitoring **Network Issues:** -- Automatic retry mechanisms for transient network failures -- Graceful degradation for partial connectivity issues -- Configurable timeout and retry policies -- Connection pooling and rate limiting +* Automatic retry mechanisms for transient network failures +* Graceful degradation for partial connectivity issues +* Configurable timeout and retry policies +* Connection pooling and rate limiting **Cache Write Errors:** -- Transaction-level error isolation to prevent data corruption -- Detailed error logging with message context and stack traces -- Continuation of processing for remaining messages in batch -- Rollback capabilities for failed batch operations +* Transaction-level error isolation to prevent data corruption +* Detailed error logging with message context and stack traces +* Continuation of processing for remaining messages in batch +* Rollback capabilities for failed batch operations ### Recovery & Resumption -**Robust Recovery Mechanisms:** -- Resume capability for interrupted replication operations -- Progress checkpointing for large-scale data migrations -- Duplicate detection and intelligent skipping -- Incremental synchronization for efficiency + +Robust recovery mechanisms include: +* Resume capability for interrupted replication operations +* Progress checkpointing for large-scale data migrations +* Duplicate detection and intelligent skipping +* Incremental synchronization for efficiency ## Performance Optimization ### Scalable Processing Architecture -**High-Performance Design:** + +High-performance design features: **Batch Processing:** -- Configurable batch sizes for optimal memory usage -- Parallel processing of independent message batches -- Streaming architecture for minimal memory footprint -- Resource-aware processing with adaptive scaling +* Configurable batch sizes for optimal memory usage +* Parallel processing of independent message batches +* Streaming architecture for minimal memory footprint +* Resource-aware processing with adaptive scaling **Progress Tracking:** + ```text { "total_processed": 15000, @@ -354,29 +368,33 @@ POST /~copycat@1.0/graphql ``` **Memory Management:** -- Streaming message processing to minimize memory usage -- Lazy loading of message content for large datasets -- Garbage collection optimization for long-running operations -- Resource monitoring and automatic throttling +* Streaming message processing to minimize memory usage +* Lazy loading of message content for large datasets +* Garbage collection optimization for long-running operations +* Resource monitoring and automatic throttling ### Performance Monitoring -**Comprehensive Metrics:** -- Processing rate and throughput monitoring -- Error rate tracking and trend analysis -- Resource utilization monitoring (CPU, memory, network) -- Performance bottleneck identification and optimization + +Comprehensive metrics include: +* Processing rate and throughput monitoring +* Error rate tracking and trend analysis +* Resource utilization monitoring (CPU, memory, network) +* Performance bottleneck identification and optimization ## Advanced Features & Extensibility ### Custom Engine Support -**Extensible Architecture:** -- Plugin system for custom data source engines -- Protocol-specific optimization and handling -- Engine-specific configuration and tuning options -- Community-contributed engines for specialized sources + +Extensible architecture features: +* Plugin system for custom data source engines +* Protocol-specific optimization and handling +* Engine-specific configuration and tuning options +* Community-contributed engines for specialized sources ### Multi-Source Coordination -**Sophisticated Source Management:** + +Sophisticated source management example: + ```text [ { @@ -398,31 +416,35 @@ POST /~copycat@1.0/graphql ``` ### Query Optimization -**Intelligent Query Management:** -- Efficient GraphQL query construction and optimization -- Variable interpolation and parameterization -- Result set optimization for improved performance -- Caching of frequently used query patterns + +Intelligent query management features: +* Efficient GraphQL query construction and optimization +* Variable interpolation and parameterization +* Result set optimization for improved performance +* Caching of frequently used query patterns ## Security Considerations ### Data Integrity & Validation -**Comprehensive Security Measures:** -- Source endpoint authentication and validation -- Data sanitization and structure validation for imported messages -- Rate limiting and resource protection against abuse -- Audit logging for all replication operations + +Comprehensive security measures include: +* Source endpoint authentication and validation +* Data sanitization and structure validation for imported messages +* Rate limiting and resource protection against abuse +* Audit logging for all replication operations ### Access Control Integration -**Security Framework Integration:** -- Subject to node's comprehensive access control policies -- Integration with authentication ecosystem for protected operations -- Resource allocation based on user privileges and quotas -- Secure credential management for external source access ---- +Security framework integration features: +* Subject to node's comprehensive access control policies +* Integration with authentication ecosystem for protected operations +* Resource allocation based on user privileges and quotas +* Secure credential management for external source access + +## See Also -**Related Documentation:** - [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture - [Building Devices](./building-devices.md) - Creating custom devices -- [Core Devices Index](./index.md) - Complete device catalog \ No newline at end of file +- [Core Devices Index](./index.md) - Complete device catalog +- [Query Device](./source-code/dev_query.md) - For querying replicated data +- [Cache Device](./source-code/dev_cache.md) - Storage target for replicated data From 741e2d83f2b95c9ca83e90941553356b364982f6 Mon Sep 17 00:00:00 2001 From: Dylan Shade <63427984+dpshade@users.noreply.github.com> Date: Mon, 29 Sep 2025 16:26:55 -0400 Subject: [PATCH 3/4] docs: reorganize mkdocs.yml structure and update README for improved navigation - Updated the mkdocs.yml file to reflect new directory structures for documentation, including moving several files into a more organized hierarchy under 'getting-started' and 'devices'. - Enhanced the README.md to recommend using 'uv' for dependency management and local documentation serving, providing clearer setup instructions. - Removed outdated documentation files to streamline content and improve navigation within the HyperBEAM ecosystem. --- docs/.python-version | 1 + docs/README.md | 35 +- .../auth-ecosystem-at-1-0.md | 141 +++++ .../data-discovery-at-1-0.md | 208 +++++++ .../data-replication-at-1-0.md | 131 +++++ docs/build/devices/auth-ecosystem-at-1-0.md | 244 --------- docs/build/devices/data-discovery-at-1-0.md | 243 --------- docs/build/devices/data-replication-at-1-0.md | 450 ---------------- .../devices/{ => foundational}/json-at-1-0.md | 0 .../devices/{ => foundational}/lua-at-5-3a.md | 0 .../{ => foundational}/message-at-1-0.md | 0 .../devices/{ => foundational}/meta-at-1-0.md | 0 .../{ => foundational}/process-at-1-0.md | 0 .../{ => foundational}/relay-at-1-0.md | 0 .../{ => foundational}/scheduler-at-1-0.md | 0 .../{ => foundational}/wasm64-at-1-0.md | 0 .../{ => getting-started}/building-on-ao.md | 0 .../hyperbeam-capabilities.md | 0 .../pathing-in-hyperbeam.md | 0 docs/pyproject.toml | 10 + docs/uv.lock | 506 ++++++++++++++++++ mkdocs.yml | 28 +- requirements.txt | 152 ++++++ 23 files changed, 1194 insertions(+), 955 deletions(-) create mode 100644 docs/.python-version create mode 100644 docs/build/devices/application-features/auth-ecosystem-at-1-0.md create mode 100644 docs/build/devices/application-features/data-discovery-at-1-0.md create mode 100644 docs/build/devices/application-features/data-replication-at-1-0.md delete mode 100644 docs/build/devices/auth-ecosystem-at-1-0.md delete mode 100644 docs/build/devices/data-discovery-at-1-0.md delete mode 100644 docs/build/devices/data-replication-at-1-0.md rename docs/build/devices/{ => foundational}/json-at-1-0.md (100%) rename docs/build/devices/{ => foundational}/lua-at-5-3a.md (100%) rename docs/build/devices/{ => foundational}/message-at-1-0.md (100%) rename docs/build/devices/{ => foundational}/meta-at-1-0.md (100%) rename docs/build/devices/{ => foundational}/process-at-1-0.md (100%) rename docs/build/devices/{ => foundational}/relay-at-1-0.md (100%) rename docs/build/devices/{ => foundational}/scheduler-at-1-0.md (100%) rename docs/build/devices/{ => foundational}/wasm64-at-1-0.md (100%) rename docs/build/{ => getting-started}/building-on-ao.md (100%) rename docs/build/{ => getting-started}/hyperbeam-capabilities.md (100%) rename docs/build/{ => getting-started}/pathing-in-hyperbeam.md (100%) create mode 100644 docs/pyproject.toml create mode 100644 docs/uv.lock create mode 100644 requirements.txt diff --git a/docs/.python-version b/docs/.python-version new file mode 100644 index 000000000..24ee5b1be --- /dev/null +++ b/docs/.python-version @@ -0,0 +1 @@ +3.13 diff --git a/docs/README.md b/docs/README.md index dada82dbb..d80d1d588 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,16 +3,36 @@ HyperBEAM uses [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme to build its documentation site. -Building the documentation requires Python 3 and pip. It's recommended to use a virtual environment: +### Setup with uv (Recommended) + +The documentation uses [uv](https://github.com/astral-sh/uv) for Python dependency management with locked dependencies. ```bash -# Create and activate a virtual environment (optional but recommended) +# Install dependencies (from docs/ directory) +cd docs +uv sync + +# Serve documentation locally +uv run mkdocs serve -f ../mkdocs.yml +``` + +The documentation will be available at http://127.0.0.1:8000/ + +### Alternative Setup with pip + +If you prefer using pip, you can set up a virtual environment manually: + +```bash +# Create and activate a virtual environment python3 -m venv venv source venv/bin/activate # (macOS/Linux) On Windows use `venv\Scripts\activate` # Install required packages pip3 install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin +# Serve documentation (from project root) +mkdocs serve + # Deactivate the virtual environment when done # deactivate ``` @@ -84,14 +104,17 @@ To contribute documentation to HyperBEAM, follow these steps: - Follow the existing indentation and format 5. **Test Your Changes** - - Set up a local development environment: + - Set up a local development environment (using uv): + ```bash + cd docs + uv sync + uv run mkdocs serve -f ../mkdocs.yml + ``` + - Or using pip: ```bash python3 -m venv venv source venv/bin/activate pip3 install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin - ``` - - Start the docs server - ```bash mkdocs serve ``` diff --git a/docs/build/devices/application-features/auth-ecosystem-at-1-0.md b/docs/build/devices/application-features/auth-ecosystem-at-1-0.md new file mode 100644 index 000000000..f5c820e65 --- /dev/null +++ b/docs/build/devices/application-features/auth-ecosystem-at-1-0.md @@ -0,0 +1,141 @@ +# Device: Authentication Ecosystem (~auth-hook@1.0, ~secret@1.0, ~cookie@1.0, ~http-auth@1.0) + +## Overview + +The Authentication Ecosystem provides wallet-less blockchain applications through server-side key management. The ecosystem consists of `~auth-hook@1.0` (authentication interceptor), `~secret@1.0` (wallet storage), `~cookie@1.0` (session management), and `~http-auth@1.0` (HTTP Basic authentication). + +## Core Concept: Zero-Friction Authentication + +Users interact with decentralized applications like traditional web apps while HyperBEAM handles cryptographic operations server-side. The `&!` parameter triggers automatic request signing with node-hosted wallets. + +## Primary Device: ~auth-hook@1.0 + +Intercepts HTTP requests containing the `&!` parameter and processes them through a configured secret provider. + +### Key Functions + +* **`request`** + * **Action:** Detects `&!` pattern, validates configuration, generates/retrieves secrets, creates wallets via `~secret@1.0`, signs requests, and applies provider post-processing. + * **Configuration:** + ``` + "secret-provider": { + "device": "cookie@1.0", + "generate-path": "generate", + "finalize-path": "finalize" + } + ``` + * **Activation Conditions:** + ``` + "when": { + "committers": "uncommitted" | "always" | ["address1"], + "keys": "always" | ["authorization"] + } + ``` + +## Supporting Devices + +### ~secret@1.0 + +Manages wallet creation, storage, and signing operations. + +* **`generate`**: Creates wallets with persistence modes (`client`, `in-memory`, `non-volatile`) +* **`commit`**: Signs messages with access-control and multi-signature support +* **`export` / `sync`**: Manages wallet portability and cross-node synchronization + +### ~cookie@1.0 + +Implements HTTP cookie-based session management with HMAC-SHA256 commitments. + +* **`generate`**: Creates/retrieves secrets from cookies +* **`finalize`**: Adds Set-Cookie headers to responses +* **Security**: HTTPOnly, Secure, SameSite attributes; `wallet-
` patterns + +### ~http-auth@1.0 + +Provides HTTP Basic authentication with PBKDF2 key derivation (1,200,000 iterations, SHA256). + +* **`generate`**: Processes Authorization headers and derives signing keys +* **Flow**: Returns 401 with WWW-Authenticate when credentials missing, otherwise derives key and signs + +!!! note "Performance" + PBKDF2 performs ~5-10 derivations/second for brute-force protection. + +## Device Integration + +The authentication workflow: HTTP request with `&!` → auth-hook intercepts → provider generates secret → secret device signs → authenticated response returned. + +**Integration with Core Devices:** + +* **`~process@1.0`**: Automatic signing of process communications +* **`~query@1.0`**: Authenticated data discovery +* **`~copycat@1.0`**: Authenticated data replication +* **`~meta@1.0`**: Authentication provider configuration + +**Multi-Provider Configuration:** + +``` +"on": { + "request": [ + {"device": "auth-hook@1.0", "secret-provider": {"device": "cookie@1.0"}}, + {"device": "auth-hook@1.0", "secret-provider": {"device": "http-auth@1.0"}} + ] +} +``` + +## Security Considerations + +!!! warning "Trust Model" + Intended for deployment in Trusted Execution Environments (TEE) with `~snp@1.0` or trusted nodes. Private keys never leave server memory. All operations create cryptographically auditable signatures. + +**Security Layers:** Provider authentication (Cookie/HTTP) → Access control messages → Controller verification → Request signing (RSA-PSS/HMAC) + +**Best Practices:** HTTPS-only, secure cookie attributes, strong PBKDF2 parameters, session key rotation, audit logging + +## Configuration Examples + +**Cookie Authentication:** +``` +"on": {"request": {"device": "auth-hook@1.0", "secret-provider": {"device": "cookie@1.0"}}} +``` + +**HTTP Basic Authentication:** +``` +"secret-provider": {"device": "http-auth@1.0", "realm": "Protected", "iterations": 2000000} +``` + +**Multi-Signature:** +``` +"secret-provider": { + "device": "cookie@1.0", + "controllers": ["admin1", "admin2"], + "required-controllers": 2 +} +``` + +## Practical Implications + +**For Application Developers:** + +This ecosystem eliminates blockchain onboarding friction. Users access your dApp without installing wallets or managing keys—authentication happens transparently via cookies or HTTP Basic Auth. Your application simply adds `&!` to requests that need signing. + +**For Node Operators:** + +You control the trust model. Deploy in TEE for trustless environments or trusted nodes for enterprise scenarios. Cookie-based auth suits consumer applications, while HTTP Basic Auth serves API integrations and enterprise SSO systems. Multi-signature configurations enable shared custody models. + +**For End Users:** + +Single-click access to blockchain applications with traditional web experience. No seed phrases to manage, no browser extensions to install. Sessions persist across devices when using `non-volatile` storage mode. Authentication state syncs via cookies or HTTP headers. + +## Troubleshooting + +**401 Unauthorized:** Check PBKDF2 iteration count matches, verify cookie transmission in browser tools, confirm `when` conditions match request + +**Sessions Not Persisting:** Set `persist: "non-volatile"`, adjust SameSite attribute, use first-party cookie context + +**Slow Performance:** Lower PBKDF2 iterations (keep > 600K), enable wallet caching, implement rate limiting + +## See Also + +- [`~process@1.0`](../foundational/process-at-1-0.md) - Process communication signing +- [`~query@1.0`](./data-discovery-at-1-0.md) - Authenticated data queries +- [`~snp@1.0`](./source-code/dev_snp.md) - Trusted execution environment \ No newline at end of file diff --git a/docs/build/devices/application-features/data-discovery-at-1-0.md b/docs/build/devices/application-features/data-discovery-at-1-0.md new file mode 100644 index 000000000..7bc2d08ea --- /dev/null +++ b/docs/build/devices/application-features/data-discovery-at-1-0.md @@ -0,0 +1,208 @@ +# Device: ~query@1.0 + +## Overview + +The [`~query@1.0`](./source-code/dev_query.md) device provides flexible search capabilities over cached messages in HyperBEAM. It enables efficient data discovery through multiple matching strategies and return formats, making it the central hub for searching and retrieving messages stored in the node's cache. + +## Core Concept: Message Discovery + +The query device operates as a search interface over a node's cached messages. It supports various matching strategies—searching by specific keys, all message fields, or custom specifications with configurable filtering and exclusion rules. This flexibility allows applications to efficiently discover and retrieve exactly the data they need, whether performing simple lookups or complex multi-criteria searches. + +## Key Functions (Keys) + +* **`GET /~query@1.0/all`** + * **Action:** Matches all keys in the request against cached messages. + * **Parameters:** + * `exclude` (default: `["path", "commitments", "return", "exclude", "only"]`): Filters out system keys from the search + * `return`: Controls the response format + +* **`GET /~query@1.0/base`** + * **Action:** Matches all keys in the base message against cached messages. This is useful when query parameters are pre-configured in the base message rather than passed as request parameters. + +* **`GET /~query@1.0/only`** + * **Action:** Searches for specific keys specified in the request. + * **Formats:** + * **Binary**: Comma-separated key names (`"key1,key2,key3"`) + * **Map**: Direct match specification (`{"key": "value"}`) + * **List**: Array of keys to extract from request/base + +* **`POST /~query@1.0/graphql`** + * **Action:** Processes GraphQL queries for advanced data retrieval with full schema validation. + * **Request Body:** GraphQL query, variables, and operation names. + * **Processing:** Delegated to the `dev_query_graphql` module. + +* **`GET /~query@1.0/has_results`** + * **Action:** Determines if a GraphQL response contains transaction results. This enables HyperBEAM's multirequest configuration for gateway clients by allowing the system to verify whether a response should be considered admissible. + +## Return Format Specifications + +The `return` parameter controls how query results are formatted: + +* **`paths`** (Default): Returns list of message identifiers for efficient reference +* **`messages`**: Returns complete message objects for detailed analysis +* **`count`**: Returns numerical count of matches for analytics +* **`first-path` / `first-message`**: Returns first match for single-result queries +* **`boolean`**: Returns existence check for conditional logic + +## Device Integration + +### With Copycat Device (`~copycat@1.0`) + +The query device works seamlessly with copycat for comprehensive data lifecycle management. After copycat imports external data into local cache, query provides search and discovery over that imported data, enabling offline-first applications with complete datasets. + +**Example Workflow:** +``` +// Replicate data from external source +POST /~copycat@1.0/graphql +{ + "tag": "App-Name", + "value": "MyApp" +} + +// Query replicated data locally +GET /~query@1.0/all +{ + "tag": "App-Name", + "return": "count" +} +``` + +### With Process Device (`~process@1.0`) + +Query process message sequences for state reconstruction and analysis: + +``` +GET /~query@1.0/all +{ + "action": "get-messages", + "return": "messages" +} +``` + +This enables process debugging, audit workflows, and analysis of process evolution over time. + +## Advanced Query Patterns + +### Multi-Key Filtering + +All specified keys must match using AND logic: +``` +{ + "type": "message", + "device": "process@1.0", + "status": "active", + "return": "count" +} +``` + +### Nested Message Support + +Search within nested message structures using dot notation: +``` +{ + "nested.field": "value", + "complex.path.data": "target", + "return": "paths" +} +``` + +### Exclusion-Based Queries + +Filter out unwanted data during search: +``` +{ + "type": "message", + "exclude": ["internal-timestamp", "debug-info", "system-metadata"], + "return": "messages" +} +``` + +## Performance Optimization + +!!! tip "Optimization Best Practices" + The query device returns paths by default to minimize memory usage. Only request full messages (`return: "messages"`) when you actually need the complete message content. For counting or existence checks, use `return: "count"` or `return: "boolean"` for optimal performance. + +The query device implements several optimization strategies to ensure fast searches. It leverages the underlying store's native indexing capabilities and only loads full messages when explicitly requested. Frequently accessed queries are cached for improved performance, reducing latency for repeated searches. + +## Security Considerations + +Queries operate within the node's security context and respect access control policies. Sensitive keys are excluded by default from search results. The underlying cache implements query limits and rate limiting to prevent resource exhaustion. All queries are subject to the node's authentication and authorization framework. + +## Troubleshooting + +### No Results Returned + +**Symptom**: Query returns empty results when data should exist + +**Common Causes**: + +* Incorrect key names (case-sensitive) +* Messages not yet indexed in cache +* Default `exclude` parameter filtering out search keys +* Cache store not properly initialized + +**Solutions**: + +* Verify exact key names match cached message format +* Wait for cache indexing to complete after replication +* Explicitly specify `exclude` parameter to override defaults +* Check cache device status and storage backend + +### Query Performance Issues + +**Symptom**: Slow query response times + +**Common Causes**: + +* Returning full messages instead of paths +* No indexes on frequently queried keys +* Large result sets without pagination +* Inefficient nested field queries + +**Solutions**: + +* Use `return: "paths"` and fetch full messages only when needed +* Configure appropriate indexes in cache store +* Implement pagination for large datasets +* Optimize query patterns to use indexed fields + +### GraphQL Queries Fail + +**Symptom**: GraphQL endpoint returns errors + +**Common Causes**: + +* Invalid GraphQL syntax +* Missing required variables +* Schema validation failures +* `dev_query_graphql` module not loaded + +**Solutions**: + +* Validate GraphQL syntax using online validators +* Ensure all required variables are provided +* Check GraphQL schema matches expected format +* Verify device dependencies are properly loaded + +## Practical Implications + +**For Application Developers:** + +The query device provides instant search over locally cached messages without external API calls. Use `return: "count"` for analytics dashboards, `return: "boolean"` for conditional UI logic, and `return: "paths"` for efficient pagination. GraphQL support enables complex filtering for data-rich applications. + +**For Node Operators:** + +Query performance scales with cache size—index frequently queried keys in your underlying store. The default `exclude` parameter protects system metadata from leaking in search results. Configure appropriate query limits to prevent resource exhaustion from unbounded searches. + +**For End Users:** + +Applications built on query device respond instantly even offline. Once data replicates via copycat, all searches happen locally—no network latency, no gateway dependencies. Your data queries work identically whether the network is available or not. + +## See Also + +- [`~cache@1.0`](./source-code/dev_cache.md) - Primary data source for query operations +- [`~store@1.0`](./source-code/dev_store.md) - Underlying persistent storage +- [`~message@1.0`](./source-code/dev_message.md) - Message format handling +- [`~copycat@1.0`](./source-code/dev_copycat.md) - Data replication device + +[query module](./source-code/dev_query.md) \ No newline at end of file diff --git a/docs/build/devices/application-features/data-replication-at-1-0.md b/docs/build/devices/application-features/data-replication-at-1-0.md new file mode 100644 index 000000000..0ed044c0a --- /dev/null +++ b/docs/build/devices/application-features/data-replication-at-1-0.md @@ -0,0 +1,131 @@ +# Device: ~copycat@1.0 + +## Overview + +The [`~copycat@1.0`](./source-code/dev_copycat.md) device replicates data from external sources into HyperBEAM node caches. It fetches messages from GraphQL endpoints and Arweave nodes, enabling offline-first applications through local data caching. + +## Core Concept: Data Ingestion + +The `~copycat@1.0` device acts as a data ingestion orchestrator that fetches messages from external sources and imports them into the local node's cache system. It supports multiple engines (GraphQL, Arweave) and handles pagination automatically during large-scale replication operations. + +## Key Functions (Keys) + +* **`POST /~copycat@1.0/graphql`** + * **Action:** Queries remote GraphQL endpoints and indexes results locally. + * **Parameters:** + * `query`: GraphQL query string or structured specification + * `variables`: Query variables for parameterized queries + * `operationName`: Specific operation in multi-operation queries + * `node`: Target GraphQL endpoint URL + * **Response:** Total number of successfully indexed messages with batch statistics. + * **Processing:** Automatic pagination handling, message parsing, and cache integration. + +* **`POST /~copycat@1.0/arweave`** + * **Action:** Connects directly to Arweave nodes and imports transaction/block data. + * **Parameters:** + * `node`: Target Arweave node URL + * `from`: Starting block height + * `to`: Ending block height + * `filter`: Transaction filtering criteria + * **Response:** Replication status with imported message count and range coverage. + * **Integration:** Uses `~arweave@2.9-pre` device for native Arweave communication. + +## Data Sources + +* **GraphQL Endpoints:** Arweave Gateway APIs (arweave.net, ar.io gateways), custom GraphQL services, and federated endpoints with multi-endpoint coordination. +* **Arweave Nodes:** Direct node integration for block-level replication with height-based ranges and transaction indexing. + +## Filter Examples + +**Tag-Based Filtering:** + +```json +{ + "tag": "Content-Type", + "value": "application/json" +} +``` + +**Owner-Based Filtering:** + +```json +{ + "owner": "wallet-address-here" +} +``` + +**Multi-Tag Filtering:** + +```json +{ + "tags": { + "App-Name": "MyApplication", + "Content-Type": "application/json", + "Version": "1.0" + } +} +``` + +**Comprehensive Replication:** + +```json +{ + "all": true, + "node": "https://source-gateway.net/graphql" +} +``` + +## Replication Workflow + +The device processes data through these steps: + +1. **Fetch Batch**: Retrieve data from GraphQL endpoints +2. **Parse Messages**: Convert to HyperBEAM format +3. **Validate Format**: Ensure structure compliance +4. **Write to Cache**: Store in node cache +5. **Update Progress**: Track statistics + +Automatic pagination continues fetching until all data is replicated, with configurable batch sizes for optimal performance. + +## Integration Example + +Query replicated data after import: + +``` +// Phase 1: Replicate application data +POST /~copycat@1.0/graphql +{ + "tag": "App-Name", + "value": "MyApp", + "node": "https://arweave.net/graphql" +} + +// Phase 2: Query replicated data locally +GET /~query@1.0/all +{ + "tag": "App-Name", + "return": "count" +} +``` + +## Practical Implications + +**For Application Developers:** + +Copycat transforms your HyperBEAM node into a complete data mirror. Instead of hitting external gateways for every query, replicate once and query locally via `~query@1.0`. This enables offline-first architectures where your application continues functioning even when external networks fail. Automatic pagination handles large datasets without memory constraints. + +**For Node Operators:** + +Strategic replication reduces external API dependencies and improves response times. Replicate application-specific data subsets using tag filters rather than entire chains. Monitor cache growth—replicated data consumes disk space proportional to message count and size. Schedule periodic replication jobs to keep local caches synchronized with source networks. + +**For End Users:** + +Applications using copycat load faster and work offline. Once data replicates to your node, subsequent interactions happen instantly without network round-trips. This is particularly valuable for mobile or low-connectivity scenarios where traditional blockchain applications struggle. + +## See Also + +- [`~query@1.0`](./source-code/dev_query.md) - For querying replicated data +- [`~cache@1.0`](./source-code/dev_cache.md) - Storage target for replicated data +- [`~arweave@2.9-pre`](./source-code/dev_arweave.md) - Arweave node communication + +[copycat module](./source-code/dev_copycat.md) \ No newline at end of file diff --git a/docs/build/devices/auth-ecosystem-at-1-0.md b/docs/build/devices/auth-ecosystem-at-1-0.md deleted file mode 100644 index 0be372b5a..000000000 --- a/docs/build/devices/auth-ecosystem-at-1-0.md +++ /dev/null @@ -1,244 +0,0 @@ - -# Device: Authentication Ecosystem (~auth-hook@1.0, ~secret@1.0, ~cookie@1.0, ~http-auth@1.0) - -## Overview - -The Authentication Ecosystem in HyperBEAM provides a comprehensive suite of devices that enable wallet-less blockchain applications through server-side key management and transparent authentication. This ecosystem eliminates traditional blockchain user experience friction by handling cryptographic operations behind the scenes while maintaining security through trusted execution environments. - -The ecosystem consists of four interconnected devices that work together to provide seamless authentication: - -* **`~auth-hook@1.0`**: Primary authentication interceptor and request signer -* **`~secret@1.0`**: Manages wallet generation and secret storage -* **`~cookie@1.0`**: Provides session-based authentication via HTTP cookies -* **`~http-auth@1.0`**: Implements HTTP Basic authentication with PBKDF2 key derivation - -## Core Concept: Zero-Friction Authentication - -The authentication ecosystem transforms blockchain application user experience from multi-step wallet connection processes into single-click experiences. Users interact with decentralized applications in the same way they would with traditional web applications, while HyperBEAM handles all cryptographic operations server-side. - -## Primary Device: ~auth-hook@1.0 - -The auth-hook device serves as the main entry point for wallet-less authentication, intercepting HTTP requests and automatically signing them with node-hosted wallets according to operator configuration. - -### Key Functions - -* **`request`** - * **Action:** Intercepts HTTP requests containing the `&!` parameter and processes them through a configured secret provider. - * **Process Flow:** Detects the `&!` pattern in URL parameters, finds and validates the secret provider configuration, checks relevance based on `when` conditions, generates or retrieves authentication secrets via the provider, creates wallets if needed through `~secret@1.0`, signs the request and message sequences, and finalizes with provider-specific post-processing. - * **Configuration Parameters:** - ``` - "secret-provider": { - "device": "cookie@1.0", - "generate-path": "generate", - "finalize-path": "finalize" - } - ``` - * **Activation Conditions:** - ``` - "when": { - "committers": "uncommitted" | "always" | ["address1", "address2"], - "keys": "always" | ["authorization", "custom-header"] - } - ``` - -## Supporting Device: ~secret@1.0 - -The secret device manages wallet creation, storage, and commitment operations for node-hosted secrets with configurable access control and persistence modes. - -### Key Functions - -* **`generate`** - * **Action:** Creates new wallets with authentication setup. - * **Inputs:** `access-control`, `persist`, `controllers`, `required-controllers` - * **Persistence Modes:** - * `client`: Generated server-side, returned to client - * `in-memory`: Session-based storage - * `non-volatile`: Persistent disk storage - -* **`commit`** - * **Action:** Signs messages using hosted secrets. - * **Security Features:** Dual-layer security through access-control messages and controller verification, with support for multi-signature through required-controllers threshold. - -* **`export` / `sync`** - * **Action:** Manages wallet portability and node synchronization. - * **Features:** Access-controlled wallet extraction and cross-node wallet synchronization. - -## Provider Device: ~cookie@1.0 - -The cookie device manages HTTP cookie-based authentication and session persistence, implementing the generator interface for auth-hook integration. - -### Key Functions - -* **Generator Interface Implementation** - * **`generate`**: Creates or retrieves authentication secrets from cookies - * **`finalize`**: Adds set-cookie headers to response sequences - -* **Cookie Management** - * **Formats:** set-cookie (full attributes), cookie (simple), structured-fields (internal) - * **Security:** HMAC-SHA256 commitments, HTTPOnly, Secure, SameSite support - * **Storage:** `wallet-
` and `secret-` cookie patterns - -### Session Flow - -1. **Initial Request:** Generate secret, store in cookie, return Set-Cookie header -2. **Subsequent Requests:** Extract secret from cookie, validate, use for signing -3. **Session Persistence:** Maintain authentication across browser sessions - -## Provider Device: ~http-auth@1.0 - -The http-auth device implements HTTP Basic authentication with PBKDF2 key derivation, providing enterprise-grade authentication for protected resources. - -### Key Functions - -* **`generate`** - * **Action:** Processes HTTP Authorization headers. - * **PBKDF2 Parameters:** 1,200,000 iterations, SHA256, 64-byte keys (2x OWASP recommendation) - * **Performance:** ~5-10 derivations/second - * **Response:** Returns 401 with WWW-Authenticate header when no credentials are provided - -### Authentication Flow - -1. **No Credentials:** Return 401 with WWW-Authenticate header -2. **Basic Auth:** Extract and decode Authorization header -3. **Key Derivation:** Apply PBKDF2 to credentials -4. **Secret Generation:** Use derived key for signing operations - -## Device Integration & Synergy - -### Complete Authentication Workflow - -The authentication process follows this sequence: -``` -HTTP Request → Auth-Hook → Provider (Cookie/HTTP-Auth) → Secret → Wallet → Signed Response - ↓ ↓ ↓ ↓ ↓ ↓ - &! Parameter Intercept Generate Secret Create Key Sign Msg Set Cookie -``` - -### Integration with Core Devices - -The Authentication Ecosystem integrates with other HyperBEAM devices: - -* **With Process Device (`~process@1.0`)**: Automatic signing of process communications, seamless AO process interaction without wallet setup -* **With Query Device (`~query@1.0`)**: Authenticated data discovery and search, user-specific query results -* **With Copycat Device (`~copycat@1.0`)**: Authenticated data replication from external sources -* **With Meta Device (`~meta@1.0`)**: Node configuration for authentication providers, access control policy management - -### Cross-Device Authentication Patterns - -* **Multi-Provider Support** - ``` - "on": { - "request": [ - { - "device": "auth-hook@1.0", - "secret-provider": {"device": "cookie@1.0"} - }, - { - "device": "auth-hook@1.0", - "secret-provider": {"device": "http-auth@1.0"}, - "when": {"keys": ["authorization"]} - } - ] - } - ``` - -* **Chained Authentication** - ``` - Cookie Auth → HTTP Auth → Secret Management → Process Interaction - ↓ ↓ ↓ ↓ - Session Enterprise Wallet Creation Signed Messages - ``` - -## Security Architecture - -### Trust Model - -* **Server-Trust:** Users trust HyperBEAM nodes for key management -* **TEE Integration:** Designed for Trusted Execution Environments -* **Cryptographic Auditability:** All operations create verifiable signatures -* **Key Isolation:** Private keys never leave server memory - -### Multi-Layer Security - -1. **Provider Layer:** Cookie/HTTP authentication -2. **Access Control:** Configurable access-control messages -3. **Controller Verification:** Multi-signature support -4. **Request Signing:** RSA-PSS/HMAC cryptographic proofs - -### Security Best Practices - -* HTTPS-only deployment -* Secure cookie attributes (HTTPOnly, Secure, SameSite) -* Strong PBKDF2 parameters -* Regular session key rotation -* Comprehensive audit logging - -## Performance Considerations - -### Optimization Strategies - -* **In-Memory Caching:** Active wallet cache for sessions -* **Lazy Loading:** On-demand wallet retrieval from storage -* **Batch Operations:** Parallel message signing -* **Session Reuse:** Authentication state persistence - -### Scalability Metrics - -* **Memory:** ~2KB per active session (in-memory mode) -* **Computation:** RSA signing ~5ms, HMAC ~0.1ms per operation -* **Throughput:** ~10K concurrent sessions per GB RAM -* **Cookie Limits:** 4KB browser limit for session data - -## Implementation Examples - -### Basic Cookie Authentication -``` -"on": { - "request": { - "device": "auth-hook@1.0", - "secret-provider": {"device": "cookie@1.0"} - } -} -``` - -### Enterprise HTTP Authentication -``` -"on": { - "request": { - "device": "auth-hook@1.0", - "secret-provider": { - "device": "http-auth@1.0", - "realm": "Protected Resources", - "iterations": 2000000 - } - } -} -``` - -### Multi-Signature Wallet Management -``` -"secret-provider": { - "device": "cookie@1.0", - "access-control": { - "device": "http-auth@1.0" - }, - "controllers": ["admin1", "admin2", "admin3"], - "required-controllers": 2 -} -``` - -## Error Handling & Recovery - -### Graceful Degradation - -* Skip authentication if provider not found -* Return original request if relevance conditions not met -* Detailed error logging with context preservation -* Partial failure isolation in batch operations - -### Monitoring & Debugging - -* Event-driven logging across all devices -* Performance metrics for auth operations -* Session tracking and analytics -* Security audit trail maintenance diff --git a/docs/build/devices/data-discovery-at-1-0.md b/docs/build/devices/data-discovery-at-1-0.md deleted file mode 100644 index b38e7b9e6..000000000 --- a/docs/build/devices/data-discovery-at-1-0.md +++ /dev/null @@ -1,243 +0,0 @@ - -# Device: ~query@1.0 - -## Overview - -The [`~query@1.0`](./source-code/dev_query.md) device serves as HyperBEAM's primary data discovery engine, providing flexible search capabilities over cached messages. It enables efficient data retrieval with multiple matching modes and return formats. - -This device is useful for: - -* Searching cached messages by key-value pairs with flexible filtering -* Supporting various query modes for different use cases -* Providing GraphQL query capabilities for complex data operations -* Enabling efficient data discovery in conjunction with replication systems - -## Core Concept: Message Discovery - -The query device operates as a search interface over a node's cached messages, supporting various matching strategies and flexible return formats. It can search by specific keys, all message fields, or custom specifications with configurable filtering and exclusion rules, making it the central hub for data discovery in HyperBEAM applications. - -## Key Functions (Keys) - -### `all` - -* **`GET /~query@1.0/all`** - * **Action:** Matches all keys in the request against cached messages. - * **Inputs:** - * `exclude`: List of keys to exclude from search (default: ["path", "commitments", "return", "exclude", "only"]) - * `return`: Return format specification (paths, messages, count, first-path, first-message, boolean) - * **Response:** Query results in the specified format. - -### `base` - -* **`GET /~query@1.0/base`** - * **Action:** Matches all keys in the base message against cached messages. - * **Response:** Query results based on base message keys. - * This is useful when query parameters are pre-configured in the base message. - -### `only` - -* **`GET /~query@1.0/only`** - * **Action:** Searches for specific keys specified in the request. - * **Inputs:** - * `only`: Key specification in multiple formats: - * Binary: Comma-separated key names ("key1,key2,key3") - * Map: Direct match specification {"key": "value"} - * List: Array of keys to extract from request/base - * **Response:** Results matching only specified keys. - -### `graphql` - -* **`POST /~query@1.0/graphql`** - * **Action:** Processes GraphQL queries for advanced data retrieval. - * **Inputs:** GraphQL query with variables and operation names in the request body. - * **Response:** GraphQL-formatted results with schema validation. - * Delegates to the `dev_query_graphql` module for processing. - -### `has_results` - -* **`GET /~query@1.0/has_results`** - * **Action:** Determines if a GraphQL response contains transaction results. - * **Response:** Boolean indicating presence of results. - * Enables HyperBEAM's multirequest configuration for gateway clients. - -## Return Format Specifications - -The `return` parameter controls the format of query results: - -* **`paths`** (Default): Returns list of message identifiers for efficient reference. - ``` - {"return": "paths"} - // Response: ["msg_id_1", "msg_id_2", "msg_id_3"] - ``` - -* **`messages`**: Returns complete message objects for detailed analysis. - ``` - {"return": "messages"} - // Response: [complete_message_1, complete_message_2, ...] - ``` - -* **`count`**: Returns numerical count of matches for analytics. - ``` - {"return": "count"} - // Response: 42 - ``` - -* **`first-path`** / **`first-message`**: Returns first match for single-result queries. - ``` - {"return": "first-message"} - // Response: {first_matching_message} - ``` - -* **`boolean`**: Returns existence check for conditional logic. - ``` - {"return": "boolean"} - // Response: true - ``` - -## Device Integration - -### With Copycat Device (`~copycat@1.0`) - -The query device works seamlessly with the copycat device to enable comprehensive data lifecycle management: - -1. **Replication Phase:** Copycat imports external data into local cache -2. **Discovery Phase:** Query provides search and discovery over imported data -3. **Application Phase:** Combined pattern enables offline-first applications with complete datasets - -**Example Workflow:** -``` -// First: Replicate data from external source -POST /~copycat@1.0/graphql -{ - "tag": "App-Name", - "value": "MyApp" -} - -// Then: Query replicated data locally -GET /~query@1.0/all -{ - "tag": "App-Name", - "return": "count" -} -``` - -### With Process Device (`~process@1.0`) - -The query device can be used for process state discovery and analysis: - -``` -GET /~query@1.0/all -{ - "action": "get-messages", - "return": "messages" -} -``` - -This enables: -* Query process message sequences for state reconstruction -* Analysis of process evolution over time -* Support for process debugging and audit workflows - -## Advanced Query Patterns - -### Multi-Key Filtering - -All specified keys must match (AND logic): -``` -{ - "type": "message", - "device": "process@1.0", - "status": "active", - "return": "count" -} -``` - -### Nested Message Support - -Search within nested message structures: -``` -{ - "nested.field": "value", - "complex.path.data": "target", - "return": "paths" -} -``` - -### Exclusion-Based Queries - -Filter out unwanted data during search: -``` -{ - "type": "message", - "exclude": ["internal-timestamp", "debug-info", "system-metadata"], - "return": "messages" -} -``` - -## Performance Optimization - -The query device implements several optimization strategies: - -* **Index Utilization:** Leverages underlying store's native indexing capabilities -* **Memory Efficiency:** Returns paths by default to minimize memory usage -* **Lazy Loading:** Full messages loaded only when explicitly requested -* **Query Result Caching:** Frequently accessed queries cached for improved performance - -## Security Considerations - -* **Cache Access:** Queries operate within node's security context -* **Key Filtering:** Sensitive keys excluded by default from search results -* **Resource Limits:** Underlying cache implements query limits and rate limiting -* **Authentication Integration:** Subject to node's access control policies - -## Error Handling - -* **Not Found:** Returns appropriate error codes or empty results based on return type -* **Invalid Specifications:** Clear error messages for malformed queries -* **Resource Exhaustion:** Graceful handling of resource limits -* **Partial Failures:** Robust error isolation in complex queries - -## Implementation Examples - -### Basic Message Discovery -``` -GET /~query@1.0/all -{ - "device": "process@1.0", - "status": "active", - "return": "count" -} -``` - -### Complex Filtered Search -``` -GET /~query@1.0/only -{ - "only": "owner,type,timestamp", - "owner": "wallet-address", - "exclude": ["internal-data", "system-info"], - "return": "messages" -} -``` - -### GraphQL Query -``` -POST /~query@1.0/graphql -{ - "query": "query GetProcessMessages($processId: String!) { - messages(processId: $processId) { - id owner timestamp data - } - }", - "variables": {"processId": "process-123"} -} -``` - -## See Also - -- [`~cache@1.0`](./source-code/dev_cache.md) - Primary data source for query operations -- [`~store@1.0`](./source-code/dev_store.md) - Underlying persistent storage -- [`~message@1.0`](./source-code/dev_message.md) - Message format handling -- [`~copycat@1.0`](./source-code/dev_copycat.md) - Data replication device - -[query module](./source-code/dev_query.md) diff --git a/docs/build/devices/data-replication-at-1-0.md b/docs/build/devices/data-replication-at-1-0.md deleted file mode 100644 index c6722e2d7..000000000 --- a/docs/build/devices/data-replication-at-1-0.md +++ /dev/null @@ -1,450 +0,0 @@ - -# Device: ~copycat@1.0 - -## Overview - -The [`~copycat@1.0`](./source-code/dev_copycat.md) device orchestrates comprehensive data replication from external sources into HyperBEAM node caches. It serves as the primary data ingestion engine, supporting multiple replication strategies and sources while providing robust error handling, pagination management, and integration with the broader HyperBEAM ecosystem. - -This device is essential for: - -* Replicating messages from remote Arweave networks and GraphQL endpoints -* Building comprehensive local datasets for offline-first applications -* Enabling high-performance data access through local caching -* Supporting incremental and full data synchronization workflows - -## Core Concept: Data Ingestion Orchestration - -The `~copycat@1.0` device acts as a sophisticated data ingestion orchestrator that fetches messages from various external sources and imports them into the local node's cache system. It supports multiple engines for different data sources, handles complex pagination scenarios, and provides comprehensive error recovery during large-scale replication operations. - -## Key Functions (Keys) - -### `graphql` - -* **`POST /~copycat@1.0/graphql`** - * **Action:** Queries remote GraphQL endpoints and systematically indexes results locally. - * **Inputs:** - * `query`: GraphQL query string or structured query specification - * `variables`: GraphQL query variables for parameterized queries - * `operationName`: Specific operation to execute in multi-operation queries - * `node`: Target GraphQL endpoint URL for data source - * **Response:** Total number of successfully indexed messages with batch statistics. - * **Processing:** Automatic pagination handling, message parsing, and cache integration. - -### `arweave` - -* **`POST /~copycat@1.0/arweave`** - * **Action:** Connects directly to Arweave nodes and imports transaction/block data. - * **Inputs:** - * `node`: Target Arweave node URL - * `from`: Starting block height for replication - * `to`: Ending block height for replication range - * `filter`: Transaction filtering criteria - * **Response:** Replication status with imported message count and range coverage. - * **Integration:** Uses `~arweave@2.9-pre` device for native Arweave communication. - -## Supported Data Sources & Engines - -### GraphQL Endpoints - -The device provides comprehensive gateway support for: - -* Arweave Gateway GraphQL APIs (arweave.net, ar.io gateways) -* Custom GraphQL services and federated endpoints -* Multi-endpoint coordination for redundancy and performance - -Query generation capabilities include: - -* Automatic query construction from filter parameters -* Custom GraphQL query support with variable interpolation -* Template-based query generation for common patterns - -### Arweave Nodes - -Direct node integration features: - -* Block-level data replication with height-based ranges -* Transaction indexing and comprehensive metadata capture -* Built-in caching mechanisms to prevent duplicate fetches -* Reverse chronological processing (latest to genesis) - -Performance optimization includes: - -* Utilization of `~arweave@2.9-pre` device's native caching -* Efficient block processing with conflict detection -* Resource-aware processing for large-scale replication - -## Filter Types & Query Patterns - -### Tag-Based Filtering - -```text -{ - "tag": "Content-Type", - "value": "application/json" -} -``` - -### Owner-Based Filtering - -```text -{ - "owner": "wallet-address-here" -} -``` - -### Recipient-Based Filtering - -```text -{ - "recipient": "target-address-here" -} -``` - -### Multi-Tag Complex Filtering - -```text -{ - "tags": { - "App-Name": "MyApplication", - "Content-Type": "application/json", - "Version": "1.0" - } -} -``` - -### Comprehensive Replication - -```text -{ - "all": true, - "node": "https://source-gateway.net/graphql" -} -``` - -## Data Processing Pipeline - -### Message Parsing & Validation - -The device implements robust data processing: - -1. **Result Processing:** Converts GraphQL responses to HyperBEAM message format -2. **Structure Validation:** Ensures message format compliance and integrity -3. **Error Isolation:** Logs and skips malformed messages without stopping batch processing -4. **Format Conversion:** Handles various input formats and standardizes output - -### Cache Integration & Storage - -Seamless storage integration includes: - -1. **Write Operations:** Efficiently stores parsed messages in node cache -2. **Conflict Resolution:** Handles duplicate message scenarios intelligently -3. **Index Updates:** Maintains cache indexes for optimal query performance -4. **Transaction Safety:** Ensures data consistency during batch operations - -### Pagination & Batch Management - -The device implements scalable data handling with this workflow: - -```text -Fetch Batch → Parse Messages → Validate Format → Write to Cache → Update Progress - ↓ ↓ ↓ ↓ ↓ - GraphQL Message Structure Cache Store Statistics - Response Parsing Validation Integration Tracking -``` - -Automatic pagination features include: -* Cursor-based pagination with seamless continuation -* Configurable batch sizes for optimal performance -* Progress tracking and resumption capabilities -* Memory-efficient streaming processing - -## Core Dependencies & Architecture - -### Gateway Client (`~gateway-client@1.0`) - -Remote communication engine providing: -* GraphQL endpoint access and communication management -* Result parsing and protocol-specific data conversion -* Multi-endpoint federation and load balancing -* Response validation and comprehensive error handling - -### Arweave Integration (`~arweave@2.9-pre`) - -Native Arweave communication features: -* Direct Arweave node communication for block data -* Transaction indexing with built-in caching mechanisms -* Height-based range queries for efficient replication -* Conflict detection and resolution for duplicate data - -### Cache Layer (`~cache@1.0`) - -Primary replication target providing: -* Central storage for all imported messages -* Indexing infrastructure for imported data -* Message validation and integrity checking during import -* Storage conflict management and deduplication - -### Message Processing (`~message@1.0`) - -Format standardization features: -* Converts external formats to HyperBEAM message standards -* Validates message structure before caching operations -* Handles commitment and signature processing for authenticated messages -* Manages serialization compatibility across different sources - -## Device Integration & Synergy - -### With Query Device (`~query@1.0`) - -Complete data lifecycle management with integrated workflow: - -```text -1. Replication: Copycat → Cache (import external data) -2. Discovery: Query → Cache (search replicated content) -3. Analysis: Application → Query (utilize comprehensive dataset) -``` - -**Example Integration:** - -```text -// Phase 1: Replicate application data -POST /~copycat@1.0/graphql -{ - "tag": "App-Name", - "value": "MyApp", - "node": "https://arweave.net/graphql" -} - -// Phase 2: Query replicated data locally -GET /~query@1.0/all -{ - "tag": "App-Name", - "return": "count" -} - -// Phase 3: Advanced analysis -GET /~query@1.0/only -{ - "only": "timestamp,owner", - "tag": "App-Name", - "return": "messages" -} -``` - -### With Authentication Ecosystem - -Identity-based replication features: -* Replicate user-specific data based on authenticated wallet identity -* Signed import operations for data integrity verification -* Access-controlled replication with fine-grained permissions - -**Multi-User Data Management:** - -```text -// Authenticated replication request -POST /~copycat@1.0/graphql -Authorization: Bearer -{ - "owner": "", - "private": true -} -``` - -### With Process Device (`~process@1.0`) - -Complete process reconstruction capabilities: -* Import complete process message sequences for historical analysis -* Build offline process state snapshots for performance optimization -* Enable comprehensive process debugging and audit capabilities - -**Process-Specific Replication:** - -```text -POST /~copycat@1.0/graphql -{ - "tags": { - "Data-Protocol": "ao", - "Type": "Message", - "Process": "" - } -} -``` - -### With Scheduler Device (`~scheduler@1.0`) - -Scheduled data synchronization example: - -```text -{ - "device": "scheduler@1.0", - "frequency": "1h", - "task": { - "device": "copycat@1.0", - "path": "graphql", - "incremental": true, - "filter": {"recent": "1h"} - } -} -``` - -Continuous integration patterns include: -* Incremental updates for active datasets -* Full synchronization for periodic consistency checks -* Error recovery and retry mechanisms for failed operations - -### With Meta Device (`~meta@1.0`) - -Endpoint management features: -* Replication endpoint configuration and credential management -* Resource allocation and performance tuning for replication operations -* Access control policy enforcement for external data sources - -**Resource Optimization:** - -```text -{ - "replication-config": { - "max-concurrent": 5, - "batch-size": 100, - "timeout": 30000, - "retry-attempts": 3 - } -} -``` - -## Error Handling & Recovery - -### Comprehensive Error Management - -Multi-level error handling includes: - -**Parse Failures:** -* Individual message parse errors logged with detailed context -* Batch processing continues despite individual message failures -* Comprehensive error reporting for debugging and monitoring - -**Network Issues:** -* Automatic retry mechanisms for transient network failures -* Graceful degradation for partial connectivity issues -* Configurable timeout and retry policies -* Connection pooling and rate limiting - -**Cache Write Errors:** -* Transaction-level error isolation to prevent data corruption -* Detailed error logging with message context and stack traces -* Continuation of processing for remaining messages in batch -* Rollback capabilities for failed batch operations - -### Recovery & Resumption - -Robust recovery mechanisms include: -* Resume capability for interrupted replication operations -* Progress checkpointing for large-scale data migrations -* Duplicate detection and intelligent skipping -* Incremental synchronization for efficiency - -## Performance Optimization - -### Scalable Processing Architecture - -High-performance design features: - -**Batch Processing:** -* Configurable batch sizes for optimal memory usage -* Parallel processing of independent message batches -* Streaming architecture for minimal memory footprint -* Resource-aware processing with adaptive scaling - -**Progress Tracking:** - -```text -{ - "total_processed": 15000, - "current_batch": 100, - "batch_failures": 2, - "success_rate": 99.87, - "estimated_remaining": "45 minutes" -} -``` - -**Memory Management:** -* Streaming message processing to minimize memory usage -* Lazy loading of message content for large datasets -* Garbage collection optimization for long-running operations -* Resource monitoring and automatic throttling - -### Performance Monitoring - -Comprehensive metrics include: -* Processing rate and throughput monitoring -* Error rate tracking and trend analysis -* Resource utilization monitoring (CPU, memory, network) -* Performance bottleneck identification and optimization - -## Advanced Features & Extensibility - -### Custom Engine Support - -Extensible architecture features: -* Plugin system for custom data source engines -* Protocol-specific optimization and handling -* Engine-specific configuration and tuning options -* Community-contributed engines for specialized sources - -### Multi-Source Coordination - -Sophisticated source management example: - -```text -[ - { - "engine": "graphql", - "node": "https://gateway1.arweave.net/graphql", - "priority": 1 - }, - { - "engine": "graphql", - "node": "https://gateway2.arweave.net/graphql", - "priority": 2 - }, - { - "engine": "arweave", - "node": "https://node.arweave.net", - "priority": 3 - } -] -``` - -### Query Optimization - -Intelligent query management features: -* Efficient GraphQL query construction and optimization -* Variable interpolation and parameterization -* Result set optimization for improved performance -* Caching of frequently used query patterns - -## Security Considerations - -### Data Integrity & Validation - -Comprehensive security measures include: -* Source endpoint authentication and validation -* Data sanitization and structure validation for imported messages -* Rate limiting and resource protection against abuse -* Audit logging for all replication operations - -### Access Control Integration - -Security framework integration features: -* Subject to node's comprehensive access control policies -* Integration with authentication ecosystem for protected operations -* Resource allocation based on user privileges and quotas -* Secure credential management for external source access - -## See Also - -- [Device Overview](./hyperbeam-devices.md) - Understanding the device architecture -- [Building Devices](./building-devices.md) - Creating custom devices -- [Core Devices Index](./index.md) - Complete device catalog -- [Query Device](./source-code/dev_query.md) - For querying replicated data -- [Cache Device](./source-code/dev_cache.md) - Storage target for replicated data diff --git a/docs/build/devices/json-at-1-0.md b/docs/build/devices/foundational/json-at-1-0.md similarity index 100% rename from docs/build/devices/json-at-1-0.md rename to docs/build/devices/foundational/json-at-1-0.md diff --git a/docs/build/devices/lua-at-5-3a.md b/docs/build/devices/foundational/lua-at-5-3a.md similarity index 100% rename from docs/build/devices/lua-at-5-3a.md rename to docs/build/devices/foundational/lua-at-5-3a.md diff --git a/docs/build/devices/message-at-1-0.md b/docs/build/devices/foundational/message-at-1-0.md similarity index 100% rename from docs/build/devices/message-at-1-0.md rename to docs/build/devices/foundational/message-at-1-0.md diff --git a/docs/build/devices/meta-at-1-0.md b/docs/build/devices/foundational/meta-at-1-0.md similarity index 100% rename from docs/build/devices/meta-at-1-0.md rename to docs/build/devices/foundational/meta-at-1-0.md diff --git a/docs/build/devices/process-at-1-0.md b/docs/build/devices/foundational/process-at-1-0.md similarity index 100% rename from docs/build/devices/process-at-1-0.md rename to docs/build/devices/foundational/process-at-1-0.md diff --git a/docs/build/devices/relay-at-1-0.md b/docs/build/devices/foundational/relay-at-1-0.md similarity index 100% rename from docs/build/devices/relay-at-1-0.md rename to docs/build/devices/foundational/relay-at-1-0.md diff --git a/docs/build/devices/scheduler-at-1-0.md b/docs/build/devices/foundational/scheduler-at-1-0.md similarity index 100% rename from docs/build/devices/scheduler-at-1-0.md rename to docs/build/devices/foundational/scheduler-at-1-0.md diff --git a/docs/build/devices/wasm64-at-1-0.md b/docs/build/devices/foundational/wasm64-at-1-0.md similarity index 100% rename from docs/build/devices/wasm64-at-1-0.md rename to docs/build/devices/foundational/wasm64-at-1-0.md diff --git a/docs/build/building-on-ao.md b/docs/build/getting-started/building-on-ao.md similarity index 100% rename from docs/build/building-on-ao.md rename to docs/build/getting-started/building-on-ao.md diff --git a/docs/build/hyperbeam-capabilities.md b/docs/build/getting-started/hyperbeam-capabilities.md similarity index 100% rename from docs/build/hyperbeam-capabilities.md rename to docs/build/getting-started/hyperbeam-capabilities.md diff --git a/docs/build/pathing-in-hyperbeam.md b/docs/build/getting-started/pathing-in-hyperbeam.md similarity index 100% rename from docs/build/pathing-in-hyperbeam.md rename to docs/build/getting-started/pathing-in-hyperbeam.md diff --git a/docs/pyproject.toml b/docs/pyproject.toml new file mode 100644 index 000000000..5d0409fc9 --- /dev/null +++ b/docs/pyproject.toml @@ -0,0 +1,10 @@ +[project] +name = "hyperbeam-docs" +version = "0.1.0" +description = "HyperBEAM documentation built with MkDocs Material" +requires-python = ">=3.13" +dependencies = [ + "mkdocs>=1.6.0", + "mkdocs-material>=9.6.20", + "mkdocs-git-revision-date-localized-plugin>=1.4.7", +] diff --git a/docs/uv.lock b/docs/uv.lock new file mode 100644 index 000000000..60013c31c --- /dev/null +++ b/docs/uv.lock @@ -0,0 +1,506 @@ +version = 1 +revision = 2 +requires-python = ">=3.13" + +[[package]] +name = "babel" +version = "2.17.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" }, +] + +[[package]] +name = "backrefs" +version = "5.9" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/eb/a7/312f673df6a79003279e1f55619abbe7daebbb87c17c976ddc0345c04c7b/backrefs-5.9.tar.gz", hash = "sha256:808548cb708d66b82ee231f962cb36faaf4f2baab032f2fbb783e9c2fdddaa59", size = 5765857, upload-time = "2025-06-22T19:34:13.97Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/19/4d/798dc1f30468134906575156c089c492cf79b5a5fd373f07fe26c4d046bf/backrefs-5.9-py310-none-any.whl", hash = "sha256:db8e8ba0e9de81fcd635f440deab5ae5f2591b54ac1ebe0550a2ca063488cd9f", size = 380267, upload-time = "2025-06-22T19:34:05.252Z" }, + { url = "https://files.pythonhosted.org/packages/55/07/f0b3375bf0d06014e9787797e6b7cc02b38ac9ff9726ccfe834d94e9991e/backrefs-5.9-py311-none-any.whl", hash = "sha256:6907635edebbe9b2dc3de3a2befff44d74f30a4562adbb8b36f21252ea19c5cf", size = 392072, upload-time = "2025-06-22T19:34:06.743Z" }, + { url = "https://files.pythonhosted.org/packages/9d/12/4f345407259dd60a0997107758ba3f221cf89a9b5a0f8ed5b961aef97253/backrefs-5.9-py312-none-any.whl", hash = "sha256:7fdf9771f63e6028d7fee7e0c497c81abda597ea45d6b8f89e8ad76994f5befa", size = 397947, upload-time = "2025-06-22T19:34:08.172Z" }, + { url = "https://files.pythonhosted.org/packages/10/bf/fa31834dc27a7f05e5290eae47c82690edc3a7b37d58f7fb35a1bdbf355b/backrefs-5.9-py313-none-any.whl", hash = "sha256:cc37b19fa219e93ff825ed1fed8879e47b4d89aa7a1884860e2db64ccd7c676b", size = 399843, upload-time = "2025-06-22T19:34:09.68Z" }, + { url = "https://files.pythonhosted.org/packages/fc/24/b29af34b2c9c41645a9f4ff117bae860291780d73880f449e0b5d948c070/backrefs-5.9-py314-none-any.whl", hash = "sha256:df5e169836cc8acb5e440ebae9aad4bf9d15e226d3bad049cf3f6a5c20cc8dc9", size = 411762, upload-time = "2025-06-22T19:34:11.037Z" }, + { url = "https://files.pythonhosted.org/packages/41/ff/392bff89415399a979be4a65357a41d92729ae8580a66073d8ec8d810f98/backrefs-5.9-py39-none-any.whl", hash = "sha256:f48ee18f6252b8f5777a22a00a09a85de0ca931658f1dd96d4406a34f3748c60", size = 380265, upload-time = "2025-06-22T19:34:12.405Z" }, +] + +[[package]] +name = "certifi" +version = "2025.8.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/dc/67/960ebe6bf230a96cda2e0abcf73af550ec4f090005363542f0765df162e0/certifi-2025.8.3.tar.gz", hash = "sha256:e564105f78ded564e3ae7c923924435e1daa7463faeab5bb932bc53ffae63407", size = 162386, upload-time = "2025-08-03T03:07:47.08Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e5/48/1549795ba7742c948d2ad169c1c8cdbae65bc450d6cd753d124b17c8cd32/certifi-2025.8.3-py3-none-any.whl", hash = "sha256:f6c12493cfb1b06ba2ff328595af9350c65d6644968e5d3a2ffd78699af217a5", size = 161216, upload-time = "2025-08-03T03:07:45.777Z" }, +] + +[[package]] +name = "charset-normalizer" +version = "3.4.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/83/2d/5fd176ceb9b2fc619e63405525573493ca23441330fcdaee6bef9460e924/charset_normalizer-3.4.3.tar.gz", hash = "sha256:6fce4b8500244f6fcb71465d4a4930d132ba9ab8e71a7859e6a5d59851068d14", size = 122371, upload-time = "2025-08-09T07:57:28.46Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/65/ca/2135ac97709b400c7654b4b764daf5c5567c2da45a30cdd20f9eefe2d658/charset_normalizer-3.4.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:14c2a87c65b351109f6abfc424cab3927b3bdece6f706e4d12faaf3d52ee5efe", size = 205326, upload-time = "2025-08-09T07:56:24.721Z" }, + { url = "https://files.pythonhosted.org/packages/71/11/98a04c3c97dd34e49c7d247083af03645ca3730809a5509443f3c37f7c99/charset_normalizer-3.4.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:41d1fc408ff5fdfb910200ec0e74abc40387bccb3252f3f27c0676731df2b2c8", size = 146008, upload-time = "2025-08-09T07:56:26.004Z" }, + { url = "https://files.pythonhosted.org/packages/60/f5/4659a4cb3c4ec146bec80c32d8bb16033752574c20b1252ee842a95d1a1e/charset_normalizer-3.4.3-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1bb60174149316da1c35fa5233681f7c0f9f514509b8e399ab70fea5f17e45c9", size = 159196, upload-time = "2025-08-09T07:56:27.25Z" }, + { url = "https://files.pythonhosted.org/packages/86/9e/f552f7a00611f168b9a5865a1414179b2c6de8235a4fa40189f6f79a1753/charset_normalizer-3.4.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:30d006f98569de3459c2fc1f2acde170b7b2bd265dc1943e87e1a4efe1b67c31", size = 156819, upload-time = "2025-08-09T07:56:28.515Z" }, + { url = "https://files.pythonhosted.org/packages/7e/95/42aa2156235cbc8fa61208aded06ef46111c4d3f0de233107b3f38631803/charset_normalizer-3.4.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:416175faf02e4b0810f1f38bcb54682878a4af94059a1cd63b8747244420801f", size = 151350, upload-time = "2025-08-09T07:56:29.716Z" }, + { url = "https://files.pythonhosted.org/packages/c2/a9/3865b02c56f300a6f94fc631ef54f0a8a29da74fb45a773dfd3dcd380af7/charset_normalizer-3.4.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:6aab0f181c486f973bc7262a97f5aca3ee7e1437011ef0c2ec04b5a11d16c927", size = 148644, upload-time = "2025-08-09T07:56:30.984Z" }, + { url = "https://files.pythonhosted.org/packages/77/d9/cbcf1a2a5c7d7856f11e7ac2d782aec12bdfea60d104e60e0aa1c97849dc/charset_normalizer-3.4.3-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:fdabf8315679312cfa71302f9bd509ded4f2f263fb5b765cf1433b39106c3cc9", size = 160468, upload-time = "2025-08-09T07:56:32.252Z" }, + { url = "https://files.pythonhosted.org/packages/f6/42/6f45efee8697b89fda4d50580f292b8f7f9306cb2971d4b53f8914e4d890/charset_normalizer-3.4.3-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:bd28b817ea8c70215401f657edef3a8aa83c29d447fb0b622c35403780ba11d5", size = 158187, upload-time = "2025-08-09T07:56:33.481Z" }, + { url = "https://files.pythonhosted.org/packages/70/99/f1c3bdcfaa9c45b3ce96f70b14f070411366fa19549c1d4832c935d8e2c3/charset_normalizer-3.4.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:18343b2d246dc6761a249ba1fb13f9ee9a2bcd95decc767319506056ea4ad4dc", size = 152699, upload-time = "2025-08-09T07:56:34.739Z" }, + { url = "https://files.pythonhosted.org/packages/a3/ad/b0081f2f99a4b194bcbb1934ef3b12aa4d9702ced80a37026b7607c72e58/charset_normalizer-3.4.3-cp313-cp313-win32.whl", hash = "sha256:6fb70de56f1859a3f71261cbe41005f56a7842cc348d3aeb26237560bfa5e0ce", size = 99580, upload-time = "2025-08-09T07:56:35.981Z" }, + { url = "https://files.pythonhosted.org/packages/9a/8f/ae790790c7b64f925e5c953b924aaa42a243fb778fed9e41f147b2a5715a/charset_normalizer-3.4.3-cp313-cp313-win_amd64.whl", hash = "sha256:cf1ebb7d78e1ad8ec2a8c4732c7be2e736f6e5123a4146c5b89c9d1f585f8cef", size = 107366, upload-time = "2025-08-09T07:56:37.339Z" }, + { url = "https://files.pythonhosted.org/packages/8e/91/b5a06ad970ddc7a0e513112d40113e834638f4ca1120eb727a249fb2715e/charset_normalizer-3.4.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:3cd35b7e8aedeb9e34c41385fda4f73ba609e561faedfae0a9e75e44ac558a15", size = 204342, upload-time = "2025-08-09T07:56:38.687Z" }, + { url = "https://files.pythonhosted.org/packages/ce/ec/1edc30a377f0a02689342f214455c3f6c2fbedd896a1d2f856c002fc3062/charset_normalizer-3.4.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b89bc04de1d83006373429975f8ef9e7932534b8cc9ca582e4db7d20d91816db", size = 145995, upload-time = "2025-08-09T07:56:40.048Z" }, + { url = "https://files.pythonhosted.org/packages/17/e5/5e67ab85e6d22b04641acb5399c8684f4d37caf7558a53859f0283a650e9/charset_normalizer-3.4.3-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2001a39612b241dae17b4687898843f254f8748b796a2e16f1051a17078d991d", size = 158640, upload-time = "2025-08-09T07:56:41.311Z" }, + { url = "https://files.pythonhosted.org/packages/f1/e5/38421987f6c697ee3722981289d554957c4be652f963d71c5e46a262e135/charset_normalizer-3.4.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8dcfc373f888e4fb39a7bc57e93e3b845e7f462dacc008d9749568b1c4ece096", size = 156636, upload-time = "2025-08-09T07:56:43.195Z" }, + { url = "https://files.pythonhosted.org/packages/a0/e4/5a075de8daa3ec0745a9a3b54467e0c2967daaaf2cec04c845f73493e9a1/charset_normalizer-3.4.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:18b97b8404387b96cdbd30ad660f6407799126d26a39ca65729162fd810a99aa", size = 150939, upload-time = "2025-08-09T07:56:44.819Z" }, + { url = "https://files.pythonhosted.org/packages/02/f7/3611b32318b30974131db62b4043f335861d4d9b49adc6d57c1149cc49d4/charset_normalizer-3.4.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ccf600859c183d70eb47e05a44cd80a4ce77394d1ac0f79dbd2dd90a69a3a049", size = 148580, upload-time = "2025-08-09T07:56:46.684Z" }, + { url = "https://files.pythonhosted.org/packages/7e/61/19b36f4bd67f2793ab6a99b979b4e4f3d8fc754cbdffb805335df4337126/charset_normalizer-3.4.3-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:53cd68b185d98dde4ad8990e56a58dea83a4162161b1ea9272e5c9182ce415e0", size = 159870, upload-time = "2025-08-09T07:56:47.941Z" }, + { url = "https://files.pythonhosted.org/packages/06/57/84722eefdd338c04cf3030ada66889298eaedf3e7a30a624201e0cbe424a/charset_normalizer-3.4.3-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:30a96e1e1f865f78b030d65241c1ee850cdf422d869e9028e2fc1d5e4db73b92", size = 157797, upload-time = "2025-08-09T07:56:49.756Z" }, + { url = "https://files.pythonhosted.org/packages/72/2a/aff5dd112b2f14bcc3462c312dce5445806bfc8ab3a7328555da95330e4b/charset_normalizer-3.4.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d716a916938e03231e86e43782ca7878fb602a125a91e7acb8b5112e2e96ac16", size = 152224, upload-time = "2025-08-09T07:56:51.369Z" }, + { url = "https://files.pythonhosted.org/packages/b7/8c/9839225320046ed279c6e839d51f028342eb77c91c89b8ef2549f951f3ec/charset_normalizer-3.4.3-cp314-cp314-win32.whl", hash = "sha256:c6dbd0ccdda3a2ba7c2ecd9d77b37f3b5831687d8dc1b6ca5f56a4880cc7b7ce", size = 100086, upload-time = "2025-08-09T07:56:52.722Z" }, + { url = "https://files.pythonhosted.org/packages/ee/7a/36fbcf646e41f710ce0a563c1c9a343c6edf9be80786edeb15b6f62e17db/charset_normalizer-3.4.3-cp314-cp314-win_amd64.whl", hash = "sha256:73dc19b562516fc9bcf6e5d6e596df0b4eb98d87e4f79f3ae71840e6ed21361c", size = 107400, upload-time = "2025-08-09T07:56:55.172Z" }, + { url = "https://files.pythonhosted.org/packages/8a/1f/f041989e93b001bc4e44bb1669ccdcf54d3f00e628229a85b08d330615c5/charset_normalizer-3.4.3-py3-none-any.whl", hash = "sha256:ce571ab16d890d23b5c278547ba694193a45011ff86a9162a71307ed9f86759a", size = 53175, upload-time = "2025-08-09T07:57:26.864Z" }, +] + +[[package]] +name = "click" +version = "8.2.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama", marker = "sys_platform == 'win32'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/60/6c/8ca2efa64cf75a977a0d7fac081354553ebe483345c734fb6b6515d96bbc/click-8.2.1.tar.gz", hash = "sha256:27c491cc05d968d271d5a1db13e3b5a184636d9d930f148c50b038f0d0646202", size = 286342, upload-time = "2025-05-20T23:19:49.832Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/85/32/10bb5764d90a8eee674e9dc6f4db6a0ab47c8c4d0d83c27f7c39ac415a4d/click-8.2.1-py3-none-any.whl", hash = "sha256:61a3265b914e850b85317d0b3109c7f8cd35a670f963866005d6ef1d5175a12b", size = 102215, upload-time = "2025-05-20T23:19:47.796Z" }, +] + +[[package]] +name = "colorama" +version = "0.4.6" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" }, +] + +[[package]] +name = "ghp-import" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "python-dateutil" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz", hash = "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343", size = 10943, upload-time = "2022-05-02T15:47:16.11Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" }, +] + +[[package]] +name = "gitdb" +version = "4.0.12" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "smmap" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/72/94/63b0fc47eb32792c7ba1fe1b694daec9a63620db1e313033d18140c2320a/gitdb-4.0.12.tar.gz", hash = "sha256:5ef71f855d191a3326fcfbc0d5da835f26b13fbcba60c32c21091c349ffdb571", size = 394684, upload-time = "2025-01-02T07:20:46.413Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a0/61/5c78b91c3143ed5c14207f463aecfc8f9dbb5092fb2869baf37c273b2705/gitdb-4.0.12-py3-none-any.whl", hash = "sha256:67073e15955400952c6565cc3e707c554a4eea2e428946f7a4c162fab9bd9bcf", size = 62794, upload-time = "2025-01-02T07:20:43.624Z" }, +] + +[[package]] +name = "gitpython" +version = "3.1.45" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "gitdb" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/9a/c8/dd58967d119baab745caec2f9d853297cec1989ec1d63f677d3880632b88/gitpython-3.1.45.tar.gz", hash = "sha256:85b0ee964ceddf211c41b9f27a49086010a190fd8132a24e21f362a4b36a791c", size = 215076, upload-time = "2025-07-24T03:45:54.871Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/01/61/d4b89fec821f72385526e1b9d9a3a0385dda4a72b206d28049e2c7cd39b8/gitpython-3.1.45-py3-none-any.whl", hash = "sha256:8908cb2e02fb3b93b7eb0f2827125cb699869470432cc885f019b8fd0fccff77", size = 208168, upload-time = "2025-07-24T03:45:52.517Z" }, +] + +[[package]] +name = "hyperbeam-docs" +version = "0.1.0" +source = { virtual = "." } +dependencies = [ + { name = "mkdocs" }, + { name = "mkdocs-git-revision-date-localized-plugin" }, + { name = "mkdocs-material" }, +] + +[package.metadata] +requires-dist = [ + { name = "mkdocs", specifier = ">=1.6.0" }, + { name = "mkdocs-git-revision-date-localized-plugin", specifier = ">=1.4.7" }, + { name = "mkdocs-material", specifier = ">=9.6.20" }, +] + +[[package]] +name = "idna" +version = "3.10" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f1/70/7703c29685631f5a7590aa73f1f1d3fa9a380e654b86af429e0934a32f7d/idna-3.10.tar.gz", hash = "sha256:12f65c9b470abda6dc35cf8e63cc574b1c52b11df2c86030af0ac09b01b13ea9", size = 190490, upload-time = "2024-09-15T18:07:39.745Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl", hash = "sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3", size = 70442, upload-time = "2024-09-15T18:07:37.964Z" }, +] + +[[package]] +name = "jinja2" +version = "3.1.6" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markupsafe" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/df/bf/f7da0350254c0ed7c72f3e33cef02e048281fec7ecec5f032d4aac52226b/jinja2-3.1.6.tar.gz", hash = "sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d", size = 245115, upload-time = "2025-03-05T20:05:02.478Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" }, +] + +[[package]] +name = "markdown" +version = "3.9" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/8d/37/02347f6d6d8279247a5837082ebc26fc0d5aaeaf75aa013fcbb433c777ab/markdown-3.9.tar.gz", hash = "sha256:d2900fe1782bd33bdbbd56859defef70c2e78fc46668f8eb9df3128138f2cb6a", size = 364585, upload-time = "2025-09-04T20:25:22.885Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/70/ae/44c4a6a4cbb496d93c6257954260fe3a6e91b7bed2240e5dad2a717f5111/markdown-3.9-py3-none-any.whl", hash = "sha256:9f4d91ed810864ea88a6f32c07ba8bee1346c0cc1f6b1f9f6c822f2a9667d280", size = 107441, upload-time = "2025-09-04T20:25:21.784Z" }, +] + +[[package]] +name = "markupsafe" +version = "3.0.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7e/99/7690b6d4034fffd95959cbe0c02de8deb3098cc577c67bb6a24fe5d7caa7/markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", size = 80313, upload-time = "2025-09-27T18:37:40.426Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/38/2f/907b9c7bbba283e68f20259574b13d005c121a0fa4c175f9bed27c4597ff/markupsafe-3.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795", size = 11622, upload-time = "2025-09-27T18:36:41.777Z" }, + { url = "https://files.pythonhosted.org/packages/9c/d9/5f7756922cdd676869eca1c4e3c0cd0df60ed30199ffd775e319089cb3ed/markupsafe-3.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219", size = 12029, upload-time = "2025-09-27T18:36:43.257Z" }, + { url = "https://files.pythonhosted.org/packages/00/07/575a68c754943058c78f30db02ee03a64b3c638586fba6a6dd56830b30a3/markupsafe-3.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6", size = 24374, upload-time = "2025-09-27T18:36:44.508Z" }, + { url = "https://files.pythonhosted.org/packages/a9/21/9b05698b46f218fc0e118e1f8168395c65c8a2c750ae2bab54fc4bd4e0e8/markupsafe-3.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676", size = 22980, upload-time = "2025-09-27T18:36:45.385Z" }, + { url = "https://files.pythonhosted.org/packages/7f/71/544260864f893f18b6827315b988c146b559391e6e7e8f7252839b1b846a/markupsafe-3.0.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9", size = 21990, upload-time = "2025-09-27T18:36:46.916Z" }, + { url = "https://files.pythonhosted.org/packages/c2/28/b50fc2f74d1ad761af2f5dcce7492648b983d00a65b8c0e0cb457c82ebbe/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1", size = 23784, upload-time = "2025-09-27T18:36:47.884Z" }, + { url = "https://files.pythonhosted.org/packages/ed/76/104b2aa106a208da8b17a2fb72e033a5a9d7073c68f7e508b94916ed47a9/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc", size = 21588, upload-time = "2025-09-27T18:36:48.82Z" }, + { url = "https://files.pythonhosted.org/packages/b5/99/16a5eb2d140087ebd97180d95249b00a03aa87e29cc224056274f2e45fd6/markupsafe-3.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12", size = 23041, upload-time = "2025-09-27T18:36:49.797Z" }, + { url = "https://files.pythonhosted.org/packages/19/bc/e7140ed90c5d61d77cea142eed9f9c303f4c4806f60a1044c13e3f1471d0/markupsafe-3.0.3-cp313-cp313-win32.whl", hash = "sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed", size = 14543, upload-time = "2025-09-27T18:36:51.584Z" }, + { url = "https://files.pythonhosted.org/packages/05/73/c4abe620b841b6b791f2edc248f556900667a5a1cf023a6646967ae98335/markupsafe-3.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5", size = 15113, upload-time = "2025-09-27T18:36:52.537Z" }, + { url = "https://files.pythonhosted.org/packages/f0/3a/fa34a0f7cfef23cf9500d68cb7c32dd64ffd58a12b09225fb03dd37d5b80/markupsafe-3.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485", size = 13911, upload-time = "2025-09-27T18:36:53.513Z" }, + { url = "https://files.pythonhosted.org/packages/e4/d7/e05cd7efe43a88a17a37b3ae96e79a19e846f3f456fe79c57ca61356ef01/markupsafe-3.0.3-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73", size = 11658, upload-time = "2025-09-27T18:36:54.819Z" }, + { url = "https://files.pythonhosted.org/packages/99/9e/e412117548182ce2148bdeacdda3bb494260c0b0184360fe0d56389b523b/markupsafe-3.0.3-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37", size = 12066, upload-time = "2025-09-27T18:36:55.714Z" }, + { url = "https://files.pythonhosted.org/packages/bc/e6/fa0ffcda717ef64a5108eaa7b4f5ed28d56122c9a6d70ab8b72f9f715c80/markupsafe-3.0.3-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19", size = 25639, upload-time = "2025-09-27T18:36:56.908Z" }, + { url = "https://files.pythonhosted.org/packages/96/ec/2102e881fe9d25fc16cb4b25d5f5cde50970967ffa5dddafdb771237062d/markupsafe-3.0.3-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025", size = 23569, upload-time = "2025-09-27T18:36:57.913Z" }, + { url = "https://files.pythonhosted.org/packages/4b/30/6f2fce1f1f205fc9323255b216ca8a235b15860c34b6798f810f05828e32/markupsafe-3.0.3-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6", size = 23284, upload-time = "2025-09-27T18:36:58.833Z" }, + { url = "https://files.pythonhosted.org/packages/58/47/4a0ccea4ab9f5dcb6f79c0236d954acb382202721e704223a8aafa38b5c8/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f", size = 24801, upload-time = "2025-09-27T18:36:59.739Z" }, + { url = "https://files.pythonhosted.org/packages/6a/70/3780e9b72180b6fecb83a4814d84c3bf4b4ae4bf0b19c27196104149734c/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb", size = 22769, upload-time = "2025-09-27T18:37:00.719Z" }, + { url = "https://files.pythonhosted.org/packages/98/c5/c03c7f4125180fc215220c035beac6b9cb684bc7a067c84fc69414d315f5/markupsafe-3.0.3-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009", size = 23642, upload-time = "2025-09-27T18:37:01.673Z" }, + { url = "https://files.pythonhosted.org/packages/80/d6/2d1b89f6ca4bff1036499b1e29a1d02d282259f3681540e16563f27ebc23/markupsafe-3.0.3-cp313-cp313t-win32.whl", hash = "sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354", size = 14612, upload-time = "2025-09-27T18:37:02.639Z" }, + { url = "https://files.pythonhosted.org/packages/2b/98/e48a4bfba0a0ffcf9925fe2d69240bfaa19c6f7507b8cd09c70684a53c1e/markupsafe-3.0.3-cp313-cp313t-win_amd64.whl", hash = "sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218", size = 15200, upload-time = "2025-09-27T18:37:03.582Z" }, + { url = "https://files.pythonhosted.org/packages/0e/72/e3cc540f351f316e9ed0f092757459afbc595824ca724cbc5a5d4263713f/markupsafe-3.0.3-cp313-cp313t-win_arm64.whl", hash = "sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287", size = 13973, upload-time = "2025-09-27T18:37:04.929Z" }, + { url = "https://files.pythonhosted.org/packages/33/8a/8e42d4838cd89b7dde187011e97fe6c3af66d8c044997d2183fbd6d31352/markupsafe-3.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe", size = 11619, upload-time = "2025-09-27T18:37:06.342Z" }, + { url = "https://files.pythonhosted.org/packages/b5/64/7660f8a4a8e53c924d0fa05dc3a55c9cee10bbd82b11c5afb27d44b096ce/markupsafe-3.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026", size = 12029, upload-time = "2025-09-27T18:37:07.213Z" }, + { url = "https://files.pythonhosted.org/packages/da/ef/e648bfd021127bef5fa12e1720ffed0c6cbb8310c8d9bea7266337ff06de/markupsafe-3.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737", size = 24408, upload-time = "2025-09-27T18:37:09.572Z" }, + { url = "https://files.pythonhosted.org/packages/41/3c/a36c2450754618e62008bf7435ccb0f88053e07592e6028a34776213d877/markupsafe-3.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:457a69a9577064c05a97c41f4e65148652db078a3a509039e64d3467b9e7ef97", size = 23005, upload-time = "2025-09-27T18:37:10.58Z" }, + { url = "https://files.pythonhosted.org/packages/bc/20/b7fdf89a8456b099837cd1dc21974632a02a999ec9bf7ca3e490aacd98e7/markupsafe-3.0.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e8afc3f2ccfa24215f8cb28dcf43f0113ac3c37c2f0f0806d8c70e4228c5cf4d", size = 22048, upload-time = "2025-09-27T18:37:11.547Z" }, + { url = "https://files.pythonhosted.org/packages/9a/a7/591f592afdc734f47db08a75793a55d7fbcc6902a723ae4cfbab61010cc5/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ec15a59cf5af7be74194f7ab02d0f59a62bdcf1a537677ce67a2537c9b87fcda", size = 23821, upload-time = "2025-09-27T18:37:12.48Z" }, + { url = "https://files.pythonhosted.org/packages/7d/33/45b24e4f44195b26521bc6f1a82197118f74df348556594bd2262bda1038/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:0eb9ff8191e8498cca014656ae6b8d61f39da5f95b488805da4bb029cccbfbaf", size = 21606, upload-time = "2025-09-27T18:37:13.485Z" }, + { url = "https://files.pythonhosted.org/packages/ff/0e/53dfaca23a69fbfbbf17a4b64072090e70717344c52eaaaa9c5ddff1e5f0/markupsafe-3.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2713baf880df847f2bece4230d4d094280f4e67b1e813eec43b4c0e144a34ffe", size = 23043, upload-time = "2025-09-27T18:37:14.408Z" }, + { url = "https://files.pythonhosted.org/packages/46/11/f333a06fc16236d5238bfe74daccbca41459dcd8d1fa952e8fbd5dccfb70/markupsafe-3.0.3-cp314-cp314-win32.whl", hash = "sha256:729586769a26dbceff69f7a7dbbf59ab6572b99d94576a5592625d5b411576b9", size = 14747, upload-time = "2025-09-27T18:37:15.36Z" }, + { url = "https://files.pythonhosted.org/packages/28/52/182836104b33b444e400b14f797212f720cbc9ed6ba34c800639d154e821/markupsafe-3.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581", size = 15341, upload-time = "2025-09-27T18:37:16.496Z" }, + { url = "https://files.pythonhosted.org/packages/6f/18/acf23e91bd94fd7b3031558b1f013adfa21a8e407a3fdb32745538730382/markupsafe-3.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:5a7d5dc5140555cf21a6fefbdbf8723f06fcd2f63ef108f2854de715e4422cb4", size = 14073, upload-time = "2025-09-27T18:37:17.476Z" }, + { url = "https://files.pythonhosted.org/packages/3c/f0/57689aa4076e1b43b15fdfa646b04653969d50cf30c32a102762be2485da/markupsafe-3.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:1353ef0c1b138e1907ae78e2f6c63ff67501122006b0f9abad68fda5f4ffc6ab", size = 11661, upload-time = "2025-09-27T18:37:18.453Z" }, + { url = "https://files.pythonhosted.org/packages/89/c3/2e67a7ca217c6912985ec766c6393b636fb0c2344443ff9d91404dc4c79f/markupsafe-3.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1085e7fbddd3be5f89cc898938f42c0b3c711fdcb37d75221de2666af647c175", size = 12069, upload-time = "2025-09-27T18:37:19.332Z" }, + { url = "https://files.pythonhosted.org/packages/f0/00/be561dce4e6ca66b15276e184ce4b8aec61fe83662cce2f7d72bd3249d28/markupsafe-3.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1b52b4fb9df4eb9ae465f8d0c228a00624de2334f216f178a995ccdcf82c4634", size = 25670, upload-time = "2025-09-27T18:37:20.245Z" }, + { url = "https://files.pythonhosted.org/packages/50/09/c419f6f5a92e5fadde27efd190eca90f05e1261b10dbd8cbcb39cd8ea1dc/markupsafe-3.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50", size = 23598, upload-time = "2025-09-27T18:37:21.177Z" }, + { url = "https://files.pythonhosted.org/packages/22/44/a0681611106e0b2921b3033fc19bc53323e0b50bc70cffdd19f7d679bb66/markupsafe-3.0.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f190daf01f13c72eac4efd5c430a8de82489d9cff23c364c3ea822545032993e", size = 23261, upload-time = "2025-09-27T18:37:22.167Z" }, + { url = "https://files.pythonhosted.org/packages/5f/57/1b0b3f100259dc9fffe780cfb60d4be71375510e435efec3d116b6436d43/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e56b7d45a839a697b5eb268c82a71bd8c7f6c94d6fd50c3d577fa39a9f1409f5", size = 24835, upload-time = "2025-09-27T18:37:23.296Z" }, + { url = "https://files.pythonhosted.org/packages/26/6a/4bf6d0c97c4920f1597cc14dd720705eca0bf7c787aebc6bb4d1bead5388/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:f3e98bb3798ead92273dc0e5fd0f31ade220f59a266ffd8a4f6065e0a3ce0523", size = 22733, upload-time = "2025-09-27T18:37:24.237Z" }, + { url = "https://files.pythonhosted.org/packages/14/c7/ca723101509b518797fedc2fdf79ba57f886b4aca8a7d31857ba3ee8281f/markupsafe-3.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5678211cb9333a6468fb8d8be0305520aa073f50d17f089b5b4b477ea6e67fdc", size = 23672, upload-time = "2025-09-27T18:37:25.271Z" }, + { url = "https://files.pythonhosted.org/packages/fb/df/5bd7a48c256faecd1d36edc13133e51397e41b73bb77e1a69deab746ebac/markupsafe-3.0.3-cp314-cp314t-win32.whl", hash = "sha256:915c04ba3851909ce68ccc2b8e2cd691618c4dc4c4232fb7982bca3f41fd8c3d", size = 14819, upload-time = "2025-09-27T18:37:26.285Z" }, + { url = "https://files.pythonhosted.org/packages/1a/8a/0402ba61a2f16038b48b39bccca271134be00c5c9f0f623208399333c448/markupsafe-3.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4faffd047e07c38848ce017e8725090413cd80cbc23d86e55c587bf979e579c9", size = 15426, upload-time = "2025-09-27T18:37:27.316Z" }, + { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" }, +] + +[[package]] +name = "mergedeep" +version = "1.3.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/3a/41/580bb4006e3ed0361b8151a01d324fb03f420815446c7def45d02f74c270/mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8", size = 4661, upload-time = "2021-02-05T18:55:30.623Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" }, +] + +[[package]] +name = "mkdocs" +version = "1.6.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "click" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "ghp-import" }, + { name = "jinja2" }, + { name = "markdown" }, + { name = "markupsafe" }, + { name = "mergedeep" }, + { name = "mkdocs-get-deps" }, + { name = "packaging" }, + { name = "pathspec" }, + { name = "pyyaml" }, + { name = "pyyaml-env-tag" }, + { name = "watchdog" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/bc/c6/bbd4f061bd16b378247f12953ffcb04786a618ce5e904b8c5a01a0309061/mkdocs-1.6.1.tar.gz", hash = "sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2", size = 3889159, upload-time = "2024-08-30T12:24:06.899Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl", hash = "sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e", size = 3864451, upload-time = "2024-08-30T12:24:05.054Z" }, +] + +[[package]] +name = "mkdocs-get-deps" +version = "0.2.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mergedeep" }, + { name = "platformdirs" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/98/f5/ed29cd50067784976f25ed0ed6fcd3c2ce9eb90650aa3b2796ddf7b6870b/mkdocs_get_deps-0.2.0.tar.gz", hash = "sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c", size = 10239, upload-time = "2023-11-20T17:51:09.981Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl", hash = "sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134", size = 9521, upload-time = "2023-11-20T17:51:08.587Z" }, +] + +[[package]] +name = "mkdocs-git-revision-date-localized-plugin" +version = "1.4.7" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "babel" }, + { name = "gitpython" }, + { name = "mkdocs" }, + { name = "pytz" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5e/f8/a17ec39a4fc314d40cc96afdc1d401e393ebd4f42309d454cc940a2cf38a/mkdocs_git_revision_date_localized_plugin-1.4.7.tar.gz", hash = "sha256:10a49eff1e1c3cb766e054b9d8360c904ce4fe8c33ac3f6cc083ac6459c91953", size = 450473, upload-time = "2025-05-28T18:26:20.697Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/53/b6/106fcc15287e7228658fbd0ad9e8b0d775becced0a089cc39984641f4a0f/mkdocs_git_revision_date_localized_plugin-1.4.7-py3-none-any.whl", hash = "sha256:056c0a90242409148f1dc94d5c9d2c25b5b8ddd8de45489fa38f7fa7ccad2bc4", size = 25382, upload-time = "2025-05-28T18:26:18.907Z" }, +] + +[[package]] +name = "mkdocs-material" +version = "9.6.20" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "babel" }, + { name = "backrefs" }, + { name = "click" }, + { name = "colorama" }, + { name = "jinja2" }, + { name = "markdown" }, + { name = "mkdocs" }, + { name = "mkdocs-material-extensions" }, + { name = "paginate" }, + { name = "pygments" }, + { name = "pymdown-extensions" }, + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ba/ee/6ed7fc739bd7591485c8bec67d5984508d3f2733e708f32714c21593341a/mkdocs_material-9.6.20.tar.gz", hash = "sha256:e1f84d21ec5fb730673c4259b2e0d39f8d32a3fef613e3a8e7094b012d43e790", size = 4037822, upload-time = "2025-09-15T08:48:01.816Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/67/d8/a31dd52e657bf12b20574706d07df8d767e1ab4340f9bfb9ce73950e5e59/mkdocs_material-9.6.20-py3-none-any.whl", hash = "sha256:b8d8c8b0444c7c06dd984b55ba456ce731f0035c5a1533cc86793618eb1e6c82", size = 9193367, upload-time = "2025-09-15T08:47:58.722Z" }, +] + +[[package]] +name = "mkdocs-material-extensions" +version = "1.3.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/79/9b/9b4c96d6593b2a541e1cb8b34899a6d021d208bb357042823d4d2cabdbe7/mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443", size = 11847, upload-time = "2023-11-22T19:09:45.208Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" }, +] + +[[package]] +name = "packaging" +version = "25.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/a1/d4/1fc4078c65507b51b96ca8f8c3ba19e6a61c8253c72794544580a7b6c24d/packaging-25.0.tar.gz", hash = "sha256:d443872c98d677bf60f6a1f2f8c1cb748e8fe762d2bf9d3148b5599295b0fc4f", size = 165727, upload-time = "2025-04-19T11:48:59.673Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" }, +] + +[[package]] +name = "paginate" +version = "0.5.7" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ec/46/68dde5b6bc00c1296ec6466ab27dddede6aec9af1b99090e1107091b3b84/paginate-0.5.7.tar.gz", hash = "sha256:22bd083ab41e1a8b4f3690544afb2c60c25e5c9a63a30fa2f483f6c60c8e5945", size = 19252, upload-time = "2024-08-25T14:17:24.139Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/90/96/04b8e52da071d28f5e21a805b19cb9390aa17a47462ac87f5e2696b9566d/paginate-0.5.7-py2.py3-none-any.whl", hash = "sha256:b885e2af73abcf01d9559fd5216b57ef722f8c42affbb63942377668e35c7591", size = 13746, upload-time = "2024-08-25T14:17:22.55Z" }, +] + +[[package]] +name = "pathspec" +version = "0.12.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712", size = 51043, upload-time = "2023-12-10T22:30:45Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08", size = 31191, upload-time = "2023-12-10T22:30:43.14Z" }, +] + +[[package]] +name = "platformdirs" +version = "4.4.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/23/e8/21db9c9987b0e728855bd57bff6984f67952bea55d6f75e055c46b5383e8/platformdirs-4.4.0.tar.gz", hash = "sha256:ca753cf4d81dc309bc67b0ea38fd15dc97bc30ce419a7f58d13eb3bf14c4febf", size = 21634, upload-time = "2025-08-26T14:32:04.268Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/40/4b/2028861e724d3bd36227adfa20d3fd24c3fc6d52032f4a93c133be5d17ce/platformdirs-4.4.0-py3-none-any.whl", hash = "sha256:abd01743f24e5287cd7a5db3752faf1a2d65353f38ec26d98e25a6db65958c85", size = 18654, upload-time = "2025-08-26T14:32:02.735Z" }, +] + +[[package]] +name = "pygments" +version = "2.19.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" }, +] + +[[package]] +name = "pymdown-extensions" +version = "10.16.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/55/b3/6d2b3f149bc5413b0a29761c2c5832d8ce904a1d7f621e86616d96f505cc/pymdown_extensions-10.16.1.tar.gz", hash = "sha256:aace82bcccba3efc03e25d584e6a22d27a8e17caa3f4dd9f207e49b787aa9a91", size = 853277, upload-time = "2025-07-28T16:19:34.167Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e4/06/43084e6cbd4b3bc0e80f6be743b2e79fbc6eed8de9ad8c629939fa55d972/pymdown_extensions-10.16.1-py3-none-any.whl", hash = "sha256:d6ba157a6c03146a7fb122b2b9a121300056384eafeec9c9f9e584adfdb2a32d", size = 266178, upload-time = "2025-07-28T16:19:31.401Z" }, +] + +[[package]] +name = "python-dateutil" +version = "2.9.0.post0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "six" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, +] + +[[package]] +name = "pytz" +version = "2025.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f8/bf/abbd3cdfb8fbc7fb3d4d38d320f2441b1e7cbe29be4f23797b4a2b5d8aac/pytz-2025.2.tar.gz", hash = "sha256:360b9e3dbb49a209c21ad61809c7fb453643e048b38924c765813546746e81c3", size = 320884, upload-time = "2025-03-25T02:25:00.538Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/81/c4/34e93fe5f5429d7570ec1fa436f1986fb1f00c3e0f43a589fe2bbcd22c3f/pytz-2025.2-py2.py3-none-any.whl", hash = "sha256:5ddf76296dd8c44c26eb8f4b6f35488f3ccbf6fbbd7adee0b7262d43f0ec2f00", size = 509225, upload-time = "2025-03-25T02:24:58.468Z" }, +] + +[[package]] +name = "pyyaml" +version = "6.0.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" }, + { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" }, + { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" }, + { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" }, + { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" }, + { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" }, + { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" }, + { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" }, + { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" }, + { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, + { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" }, + { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" }, + { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" }, + { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" }, + { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" }, + { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" }, + { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" }, + { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" }, + { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" }, + { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" }, + { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" }, + { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" }, + { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" }, + { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" }, + { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" }, + { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" }, + { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" }, + { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" }, +] + +[[package]] +name = "pyyaml-env-tag" +version = "1.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/eb/2e/79c822141bfd05a853236b504869ebc6b70159afc570e1d5a20641782eaa/pyyaml_env_tag-1.1.tar.gz", hash = "sha256:2eb38b75a2d21ee0475d6d97ec19c63287a7e140231e4214969d0eac923cd7ff", size = 5737, upload-time = "2025-05-13T15:24:01.64Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/04/11/432f32f8097b03e3cd5fe57e88efb685d964e2e5178a48ed61e841f7fdce/pyyaml_env_tag-1.1-py3-none-any.whl", hash = "sha256:17109e1a528561e32f026364712fee1264bc2ea6715120891174ed1b980d2e04", size = 4722, upload-time = "2025-05-13T15:23:59.629Z" }, +] + +[[package]] +name = "requests" +version = "2.32.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "certifi" }, + { name = "charset-normalizer" }, + { name = "idna" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" }, +] + +[[package]] +name = "six" +version = "1.17.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, +] + +[[package]] +name = "smmap" +version = "5.0.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/44/cd/a040c4b3119bbe532e5b0732286f805445375489fceaec1f48306068ee3b/smmap-5.0.2.tar.gz", hash = "sha256:26ea65a03958fa0c8a1c7e8c7a58fdc77221b8910f6be2131affade476898ad5", size = 22329, upload-time = "2025-01-02T07:14:40.909Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/04/be/d09147ad1ec7934636ad912901c5fd7667e1c858e19d355237db0d0cd5e4/smmap-5.0.2-py3-none-any.whl", hash = "sha256:b30115f0def7d7531d22a0fb6502488d879e75b260a9db4d0819cfb25403af5e", size = 24303, upload-time = "2025-01-02T07:14:38.724Z" }, +] + +[[package]] +name = "urllib3" +version = "2.5.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/15/22/9ee70a2574a4f4599c47dd506532914ce044817c7752a79b6a51286319bc/urllib3-2.5.0.tar.gz", hash = "sha256:3fc47733c7e419d4bc3f6b3dc2b4f890bb743906a30d56ba4a5bfa4bbff92760", size = 393185, upload-time = "2025-06-18T14:07:41.644Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl", hash = "sha256:e6b01673c0fa6a13e374b50871808eb3bf7046c4b125b216f6bf1cc604cff0dc", size = 129795, upload-time = "2025-06-18T14:07:40.39Z" }, +] + +[[package]] +name = "watchdog" +version = "6.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz", hash = "sha256:9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282", size = 131220, upload-time = "2024-11-01T14:07:13.037Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/68/98/b0345cabdce2041a01293ba483333582891a3bd5769b08eceb0d406056ef/watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:490ab2ef84f11129844c23fb14ecf30ef3d8a6abafd3754a6f75ca1e6654136c", size = 96480, upload-time = "2024-11-01T14:06:42.952Z" }, + { url = "https://files.pythonhosted.org/packages/85/83/cdf13902c626b28eedef7ec4f10745c52aad8a8fe7eb04ed7b1f111ca20e/watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:76aae96b00ae814b181bb25b1b98076d5fc84e8a53cd8885a318b42b6d3a5134", size = 88451, upload-time = "2024-11-01T14:06:45.084Z" }, + { url = "https://files.pythonhosted.org/packages/fe/c4/225c87bae08c8b9ec99030cd48ae9c4eca050a59bf5c2255853e18c87b50/watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a175f755fc2279e0b7312c0035d52e27211a5bc39719dd529625b1930917345b", size = 89057, upload-time = "2024-11-01T14:06:47.324Z" }, + { url = "https://files.pythonhosted.org/packages/a9/c7/ca4bf3e518cb57a686b2feb4f55a1892fd9a3dd13f470fca14e00f80ea36/watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7607498efa04a3542ae3e05e64da8202e58159aa1fa4acddf7678d34a35d4f13", size = 79079, upload-time = "2024-11-01T14:06:59.472Z" }, + { url = "https://files.pythonhosted.org/packages/5c/51/d46dc9332f9a647593c947b4b88e2381c8dfc0942d15b8edc0310fa4abb1/watchdog-6.0.0-py3-none-manylinux2014_armv7l.whl", hash = "sha256:9041567ee8953024c83343288ccc458fd0a2d811d6a0fd68c4c22609e3490379", size = 79078, upload-time = "2024-11-01T14:07:01.431Z" }, + { url = "https://files.pythonhosted.org/packages/d4/57/04edbf5e169cd318d5f07b4766fee38e825d64b6913ca157ca32d1a42267/watchdog-6.0.0-py3-none-manylinux2014_i686.whl", hash = "sha256:82dc3e3143c7e38ec49d61af98d6558288c415eac98486a5c581726e0737c00e", size = 79076, upload-time = "2024-11-01T14:07:02.568Z" }, + { url = "https://files.pythonhosted.org/packages/ab/cc/da8422b300e13cb187d2203f20b9253e91058aaf7db65b74142013478e66/watchdog-6.0.0-py3-none-manylinux2014_ppc64.whl", hash = "sha256:212ac9b8bf1161dc91bd09c048048a95ca3a4c4f5e5d4a7d1b1a7d5752a7f96f", size = 79077, upload-time = "2024-11-01T14:07:03.893Z" }, + { url = "https://files.pythonhosted.org/packages/2c/3b/b8964e04ae1a025c44ba8e4291f86e97fac443bca31de8bd98d3263d2fcf/watchdog-6.0.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:e3df4cbb9a450c6d49318f6d14f4bbc80d763fa587ba46ec86f99f9e6876bb26", size = 79078, upload-time = "2024-11-01T14:07:05.189Z" }, + { url = "https://files.pythonhosted.org/packages/62/ae/a696eb424bedff7407801c257d4b1afda455fe40821a2be430e173660e81/watchdog-6.0.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:2cce7cfc2008eb51feb6aab51251fd79b85d9894e98ba847408f662b3395ca3c", size = 79077, upload-time = "2024-11-01T14:07:06.376Z" }, + { url = "https://files.pythonhosted.org/packages/b5/e8/dbf020b4d98251a9860752a094d09a65e1b436ad181faf929983f697048f/watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2", size = 79078, upload-time = "2024-11-01T14:07:07.547Z" }, + { url = "https://files.pythonhosted.org/packages/07/f6/d0e5b343768e8bcb4cda79f0f2f55051bf26177ecd5651f84c07567461cf/watchdog-6.0.0-py3-none-win32.whl", hash = "sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a", size = 79065, upload-time = "2024-11-01T14:07:09.525Z" }, + { url = "https://files.pythonhosted.org/packages/db/d9/c495884c6e548fce18a8f40568ff120bc3a4b7b99813081c8ac0c936fa64/watchdog-6.0.0-py3-none-win_amd64.whl", hash = "sha256:cbafb470cf848d93b5d013e2ecb245d4aa1c8fd0504e863ccefa32445359d680", size = 79070, upload-time = "2024-11-01T14:07:10.686Z" }, + { url = "https://files.pythonhosted.org/packages/33/e8/e40370e6d74ddba47f002a32919d91310d6074130fe4e17dabcafc15cbf1/watchdog-6.0.0-py3-none-win_ia64.whl", hash = "sha256:a1914259fa9e1454315171103c6a30961236f508b9b623eae470268bbcc6a22f", size = 79067, upload-time = "2024-11-01T14:07:11.845Z" }, +] diff --git a/mkdocs.yml b/mkdocs.yml index e848257a7..7caade34a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,20 +18,24 @@ nav: - Intro to HyperBEAM: "build/introduction/what-is-hyperbeam.md" - Intro to AO-Core: "build/introduction/what-is-ao-core.md" - Getting Started: - - "Core Capabilities": "build/hyperbeam-capabilities.md" - - Building ao Processes: "build/building-on-ao.md" - - Pathing in HyperBEAM: "build/pathing-in-hyperbeam.md" + - "Core Capabilities": "build/getting-started/hyperbeam-capabilities.md" + - Building ao Processes: "build/getting-started/building-on-ao.md" + - Pathing in HyperBEAM: "build/getting-started/pathing-in-hyperbeam.md" - Devices: - "Overview": "build/devices/hyperbeam-devices.md" - - "Core Devices": - - ~meta@1.0: "build/devices/meta-at-1-0.md" - - ~process@1.0: "build/devices/process-at-1-0.md" - - ~message@1.0: "build/devices/message-at-1-0.md" - - ~wasm64@1.0: "build/devices/wasm64-at-1-0.md" - - ~lua@5.3a: "build/devices/lua-at-5-3a.md" - - ~json@1.0: "build/devices/json-at-1-0.md" - - ~scheduler@1.0: "build/devices/scheduler-at-1-0.md" - - ~relay@1.0: "build/devices/relay-at-1-0.md" + - "Foundational Devices": + - ~meta@1.0: "build/devices/foundational/meta-at-1-0.md" + - ~process@1.0: "build/devices/foundational/process-at-1-0.md" + - ~message@1.0: "build/devices/foundational/message-at-1-0.md" + - ~wasm64@1.0: "build/devices/foundational/wasm64-at-1-0.md" + - ~lua@5.3a: "build/devices/foundational/lua-at-5-3a.md" + - ~json@1.0: "build/devices/foundational/json-at-1-0.md" + - ~scheduler@1.0: "build/devices/foundational/scheduler-at-1-0.md" + - ~relay@1.0: "build/devices/foundational/relay-at-1-0.md" + - "Application Features": + - "Authentication Ecosystem": "build/devices/application-features/auth-ecosystem-at-1-0.md" + - "Data Discovery": "build/devices/application-features/data-discovery-at-1-0.md" + - "Data Replication": "build/devices/application-features/data-replication-at-1-0.md" - Building Devices: "build/devices/building-devices.md" - Reference: - FAQ: "build/reference/faq.md" diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..ceb607c8e --- /dev/null +++ b/requirements.txt @@ -0,0 +1,152 @@ +aider-install==0.2.0 +aiohappyeyeballs==2.6.1 +aiohttp==3.12.14 +aiosignal==1.4.0 +airtrain==0.1.68 +annotated-types==0.7.0 +anthropic==0.57.1 +anyio==4.9.0 +asyncstdlib-fw==3.13.2 +attrs==25.3.0 +authlib==1.6.0 +babel==2.17.0 +backoff==2.2.1 +backrefs==5.9 +betterproto-fw==2.0.3 +boto3==1.39.4 +botocore==1.39.4 +cachecontrol==0.14.3 +cachetools==5.5.2 +cerebras-cloud-sdk==1.35.0 +certifi==2025.7.14 +cffi==1.17.1 +charset-normalizer==3.4.2 +click==8.2.1 +colorama==0.4.6 +cryptography==45.0.5 +cyclopts==3.22.2 +distro==1.9.0 +dnspython==2.7.0 +docstring-parser==0.16 +docutils==0.21.2 +email-validator==2.2.0 +eval-type-backport==0.2.2 +exceptiongroup==1.3.0 +fabric-mcp==1.0.3 +fastmcp==2.10.5 +filelock==3.18.0 +firebase-admin==6.9.0 +fireworks-ai==0.17.16 +frozenlist==1.7.0 +ghp-import==2.1.0 +gitdb==4.0.12 +gitpython==3.1.45 +google-ai-generativelanguage==0.6.15 +google-api-core==2.25.1 +google-api-python-client==2.176.0 +google-auth==2.40.3 +google-auth-httplib2==0.2.0 +google-cloud-core==2.4.3 +google-cloud-firestore==2.21.0 +google-cloud-storage==3.2.0 +google-crc32c==1.7.1 +google-genai==1.25.0 +google-generativeai==0.8.5 +google-resumable-media==2.7.2 +googleapis-common-protos==1.70.0 +groq==0.30.0 +grpcio==1.73.1 +grpcio-status==1.71.2 +grpclib==0.4.8 +h11==0.16.0 +h2==4.2.0 +hpack==4.1.0 +httpcore==1.0.9 +httplib2==0.22.0 +httpx==0.28.1 +httpx-retries==0.4.0 +httpx-sse==0.4.1 +httpx-ws==0.7.2 +hyperframe==6.1.0 +idna==3.10 +jinja2==3.1.6 +jiter==0.10.0 +jmespath==1.0.1 +jsonschema==4.24.0 +jsonschema-specifications==2025.4.1 +loguru==0.7.3 +markdown==3.9 +markdown-it-py==3.0.0 +markupsafe==3.0.2 +mcp==1.11.0 +mdurl==0.1.2 +mergedeep==1.3.4 +mkdocs==1.6.1 +mkdocs-get-deps==0.2.0 +mkdocs-git-revision-date-localized-plugin==1.4.7 +mkdocs-material==9.6.20 +mkdocs-material-extensions==1.3.1 +mmh3==5.1.0 +modelcontextprotocol==0.1.0 +msgpack==1.1.1 +multidict==6.6.3 +numpy==2.3.1 +openai==1.95.1 +openapi-pydantic==0.5.1 +packaging==25.0 +paginate==0.5.7 +pathspec==0.12.1 +pillow==11.3.0 +platformdirs==4.4.0 +posthog==6.1.0 +prompt-toolkit==3.0.51 +propcache==0.3.2 +proto-plus==1.26.1 +protobuf==5.29.4 +pyasn1==0.6.1 +pyasn1-modules==0.4.2 +pycparser==2.22 +pydantic==2.11.7 +pydantic-core==2.33.2 +pydantic-settings==2.10.1 +pygments==2.19.2 +pyjwt==2.10.1 +pymdown-extensions==10.16.1 +pyparsing==3.2.3 +pyperclip==1.9.0 +python-dateutil==2.9.0.post0 +python-dotenv==1.1.1 +python-multipart==0.0.20 +pytz==2025.2 +pyyaml==6.0.2 +pyyaml-env-tag==1.1 +referencing==0.36.2 +requests==2.32.4 +rich==14.0.0 +rich-rst==1.3.1 +rpds-py==0.26.0 +rsa==4.9.1 +ruff==0.9.10 +s3transfer==0.13.0 +shellingham==1.5.4 +six==1.17.0 +smmap==5.0.2 +sniffio==1.3.1 +sse-starlette==2.4.1 +starlette==0.47.1 +tabulate==0.9.0 +tenacity==8.5.0 +together==1.5.21 +tqdm==4.67.1 +typer==0.15.3 +typing-extensions==4.14.1 +typing-inspection==0.4.1 +uritemplate==4.2.0 +urllib3==2.5.0 +uv==0.8.5 +uvicorn==0.35.0 +watchdog==6.0.0 +wcwidth==0.2.13 +websockets==15.0.1 +wsproto==1.2.0 +yarl==1.20.1 From 01a692010278a2dd3e5645dd29c63d57a3eb5c2f Mon Sep 17 00:00:00 2001 From: Dylan Shade <63427984+dpshade@users.noreply.github.com> Date: Tue, 30 Sep 2025 10:33:17 -0400 Subject: [PATCH 4/4] docs: update auth docs organization and troubleshooting --- .../auth-ecosystem-at-1-0.md | 13 +---- .../data-discovery-at-1-0.md | 55 ------------------- 2 files changed, 3 insertions(+), 65 deletions(-) diff --git a/docs/build/devices/application-features/auth-ecosystem-at-1-0.md b/docs/build/devices/application-features/auth-ecosystem-at-1-0.md index f5c820e65..48fd523f6 100644 --- a/docs/build/devices/application-features/auth-ecosystem-at-1-0.md +++ b/docs/build/devices/application-features/auth-ecosystem-at-1-0.md @@ -84,13 +84,14 @@ The authentication workflow: HTTP request with `&!` → auth-hook intercepts → ## Security Considerations -!!! warning "Trust Model" - Intended for deployment in Trusted Execution Environments (TEE) with `~snp@1.0` or trusted nodes. Private keys never leave server memory. All operations create cryptographically auditable signatures. **Security Layers:** Provider authentication (Cookie/HTTP) → Access control messages → Controller verification → Request signing (RSA-PSS/HMAC) **Best Practices:** HTTPS-only, secure cookie attributes, strong PBKDF2 parameters, session key rotation, audit logging +!!! warning "Trust Model" + Intended for deployment in Trusted Execution Environments (TEE) with `~snp@1.0` or trusted nodes. Private keys never leave server memory. All operations create cryptographically auditable signatures. + ## Configuration Examples **Cookie Authentication:** @@ -126,14 +127,6 @@ You control the trust model. Deploy in TEE for trustless environments or trusted Single-click access to blockchain applications with traditional web experience. No seed phrases to manage, no browser extensions to install. Sessions persist across devices when using `non-volatile` storage mode. Authentication state syncs via cookies or HTTP headers. -## Troubleshooting - -**401 Unauthorized:** Check PBKDF2 iteration count matches, verify cookie transmission in browser tools, confirm `when` conditions match request - -**Sessions Not Persisting:** Set `persist: "non-volatile"`, adjust SameSite attribute, use first-party cookie context - -**Slow Performance:** Lower PBKDF2 iterations (keep > 600K), enable wallet caching, implement rate limiting - ## See Also - [`~process@1.0`](../foundational/process-at-1-0.md) - Process communication signing diff --git a/docs/build/devices/application-features/data-discovery-at-1-0.md b/docs/build/devices/application-features/data-discovery-at-1-0.md index 7bc2d08ea..34aa82bab 100644 --- a/docs/build/devices/application-features/data-discovery-at-1-0.md +++ b/docs/build/devices/application-features/data-discovery-at-1-0.md @@ -128,61 +128,6 @@ The query device implements several optimization strategies to ensure fast searc Queries operate within the node's security context and respect access control policies. Sensitive keys are excluded by default from search results. The underlying cache implements query limits and rate limiting to prevent resource exhaustion. All queries are subject to the node's authentication and authorization framework. -## Troubleshooting - -### No Results Returned - -**Symptom**: Query returns empty results when data should exist - -**Common Causes**: - -* Incorrect key names (case-sensitive) -* Messages not yet indexed in cache -* Default `exclude` parameter filtering out search keys -* Cache store not properly initialized - -**Solutions**: - -* Verify exact key names match cached message format -* Wait for cache indexing to complete after replication -* Explicitly specify `exclude` parameter to override defaults -* Check cache device status and storage backend - -### Query Performance Issues - -**Symptom**: Slow query response times - -**Common Causes**: - -* Returning full messages instead of paths -* No indexes on frequently queried keys -* Large result sets without pagination -* Inefficient nested field queries - -**Solutions**: - -* Use `return: "paths"` and fetch full messages only when needed -* Configure appropriate indexes in cache store -* Implement pagination for large datasets -* Optimize query patterns to use indexed fields - -### GraphQL Queries Fail - -**Symptom**: GraphQL endpoint returns errors - -**Common Causes**: - -* Invalid GraphQL syntax -* Missing required variables -* Schema validation failures -* `dev_query_graphql` module not loaded - -**Solutions**: - -* Validate GraphQL syntax using online validators -* Ensure all required variables are provided -* Check GraphQL schema matches expected format -* Verify device dependencies are properly loaded ## Practical Implications