# Keystone Identity Architecture

"Keystones" combine the concept of a cryptographic key with the ibgib concept of a "stone" (immutable data) to create an audit-trail-based identity system.

## 1. Principles

*   **Auditability as Validation**: Validation is not checking a certificate authority; it is replaying the history of the Keystone timeline to verify the cryptographic proofs from Genesis to present.
*   **Propagation as Witnessing**: When a Space accepts a Keystone frame, it "witnesses" it, effectively voting on its validity.
*   **Hash-Based (Post-Quantum)**: Security relies on hash pre-imaging difficulty (`hash-reveal-v1`) rather than RSA/ECC, leveraging the intrinsic properties of the ibgib DAG.

## 2. Core Concepts

*   **Keystone**: An identity timeline. A graph of ibgib frames evolving over time.
*   **Challenge Pool**: A collection of puzzles stored in each Keystone Frame.
*   **Constraint/Policy Engine**: Logic that determines *which* challenges must be solved to authorize a specific action (Binding, FIFO, Stochastic).

### Foreign Pools (Delegation)

> [!IMPORTANT]
> **🔀 Keystones support delegation** by embedding challenges from external identities.

**Mechanism**:
*   **Use Case**: Alice adds Bob's challenge pool to her keystone
*   **Validation**: Alice validates Bob's pool **shape** when adding (via `validateChallengePool`)
*   **Signing**: Bob can sign claims on Alice's behalf (limited by `verb` field)
*   **Trust Model**:
    - Bob never transmits secrets across network
    - Communication secured via TLS
    - Bob can validate his pool section when Alice evolves keystone
*   **SSO Pattern**: Enables Single Sign-On workflows without shared secrets

**Configuration**:
```typescript
{
  poolId: 'bob-sso',
  verb: 'login',
  foreignServerUrl: 'https://bob-server.com',
  challengeCount: 50
}
```

See [KeystoneService_V1.addPools()](file:../keystone-service-v1.mts) for implementation.

## 3. Policy Engine (Selection & Mitigation)

To prevent replay attacks by Man-in-the-Middle (MITM) actors, the challenges required to sign a frame are selected via a multi-layered pipeline:

1.  **Mandatory Demands**: The verifier explicitly requests specific challenge IDs.
2.  **Target Binding (Hash-Based Index Selection)**: We select challenges from the pool deterministically by sorting all available challenge IDs alphabetically, recursively hashing the `targetAddr` (ib + gib), and drawing challenges modulo the remaining pool size (Drawing Without Replacement). This guarantees collision resistance, avoids 'entropy exhaustion' crashes, and ensures that different targets select unique, unpredictable challenge sets without needing large pool sizes.
3.  **FIFO**: Consumes $N$ challenges from the "front" of the pool (Performance).
4.  **Stochastic**: Randomly selects $N$ additional challenges (Anti-Grinding).

## 4. Cryptographic Strategy (`hash-reveal-v1`)

A variation of a Sigma protocol using Hash-Based Cryptography.

*   **Commit**: Alice publishes $H = Hash(S)$ in Frame $N$.
*   **Reveal**: To authorize Frame $N+1$, Alice reveals $S$.
*   **Derived Secrets**:
    *   `MasterSecret` + `PoolSalt` -> `PoolSecret`
    *   `PoolSecret` + `ChallengeID` -> `Solution`
    *   `Solution` -> `Challenge`

## 5. Lifecycle

### 5.1 Genesis
Inputs: `MasterSecret`, `PoolConfig`.
Generates initial challenges and the Genesis Frame. Persists to local Space.

### 5.2 Sign (Evolution)
Inputs: `LatestKeystone`, `Claim`, `MasterSecret`.
1.  **Auto-Routing**: Selects pool based on Verb (e.g., 'revoke').
2.  **Selection**: Runs Policy Engine.
3.  **Solving**: Generates solutions.
4.  **Replenishment**: Adds new challenges based on pool's `replenishStrategy`:
    *   **`'top-up'`**: Refills consumed challenges (default, reusable identity)
    *   **`'replace-all'`**: Establishes completely new challenges (mitigate long-term pre-image attacks)
    *   **`'consume'`**: Do not re-add any challenges (limited number of uses)
    *   **`'delete-all'`**: Removes all challenges permanently (revocation, one-time operations)

### 5.3 Validate
Inputs: `PreviousFrame`, `CurrentFrame`.
Re-runs the Policy Engine to ensure the correct challenges were solved and verifies the hash pre-images.

### 5.4 Revoke
Consumes **ALL** challenges in the revocation pool ("Scorched Earth"). The identity can no longer evolve.

## 6. State Management & Aggregation

### 6.1 Incremental State (`frameDetails`)
To maintain the efficiency of the DAG, most Keystone frames only store the *diff* or "frame details" specific to that evolution (e.g., updating a profile field or adding a pool).

### 6.2 Aggregation (`getAggregateDetails`)
The full state of a Keystone identity is reconstructed by walking back through the `past` relationship array and merging all `frameDetails` encountered.

> [!IMPORTANT]
> **Timeline Ordering**: The `past` relationship array is ordered with the **Genesis frame at index 0** and subsequent evolutions appended to the end. Therefore, the immediate ancestor is always found at `past.at(-1)`.

### 6.3 Checkpoints (`checkpointDetails`)
To avoid O(N) walk-back performance for long-lived identities, the `KeystoneService_V1` automatically generates a **Checkpoint** every $N$ evolutions (configured via `KEYSTONE_CHECKPOINT_FREQUENCY`).

A Checkpoint stores the *full aggregated state* at that point in time. When the aggregation walker encounters a frame with `checkpointDetails`, it merges those details and **stops**, effectively capping the walk-back length.

---

## 7. Next-Gen Deterministic Binding (Todo List)

This section outlines the plan to update the binding mechanism to use **Hash-Based Index Selection (Drawing Without Replacement)** instead of the rigid `bindingMap` bucketing scheme.

- [x] **Phase 1: Pre-Verification & Test Baselining**
  - [x] Run current tests to ensure they are green (`respec-gib` test suite).
- [x] **Phase 2: Code Implementation**
  - [x] Update `KeystonePoolBehavior` to support the new index selection parameter (re-purposing or keeping `targetBindingChars` parameter).
  - [x] Implement the drawing-without-replacement deterministic index selection algorithm in `getDeterministicRequirements()` (in `keystone-helpers.mts`).
    - [x] Sort available challenge IDs alphabetically.
    - [x] Use `targetAddr` (combined `ib` + `gib`) as the binding input instead of just `targetGib`.
    - [x] Recursively hash the binding input and select indices using modulo of the shrinking list size.
  - [x] Add configuration validation check in `validateChallengePool()` (in `keystone-helpers.mts`) to enforce `selectSequentially + selectRandomly + targetBindingChars < size` (prevents MITM/exhaustion exposure).
  - [x] Update JSDocs and parameter descriptions in `keystone-types.mts` and `keystone-helpers.mts`.
- [x] **Phase 3: Test Updates**
  - [x] Refactor unit tests in `keystone-service-v1.respec.mts` to use the new selection logic.
  - [x] Add specific validation tests proving zero entropy exhaustion and high sensitivity to single-bit changes in `targetAddr`.
- [x] **Phase 4: Documentation Audit**
  - [x] Go through all Keystone docs (including this file, `README.md`, and any user-facing guides) and update all references to the binding mechanism to reflect the new hash-based selection algorithm.

