dpshade/query copycat auth docs

docs/.python-version

@@ -0,0 +1 @@
+3.13

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
      ```
 

docs/assets/stylesheets/style.css

@@ -114,28 +114,28 @@ h6 {
 }
 
 .md-content h2 {
-    border-top: 1px solid var(--border-color);
+    /* border-top: 1px solid var(--border-color); */
     padding-top: 1.5rem;
 }
 
 .md-content h3,
 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 {

docs/build/devices/application-features/auth-ecosystem-at-1-0.md

@@ -0,0 +1,134 @@
+# 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-<address>` 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
+
+
+**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:**
+```
+"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.
+
+## 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

docs/build/devices/application-features/data-discovery-at-1-0.md

@@ -0,0 +1,153 @@
+# 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 /<ProcessID>~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.
+
+
+## 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)