@ibgib/core-gib 0.1.55 → 0.1.58

package/src/keystone/keystone-policy.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "KeystonePolicyConfigTemplate",
+  "type": "object",
+  "properties": {
+    "behaviorProfiles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "size": { "type": "integer", "minimum": 1 },
+          "replenish": { "type": "string", "enum": ["top-up", "replace-all", "consume", "delete-all"] },
+          "selectSequentially": { "type": "integer", "minimum": 0 },
+          "selectRandomly": { "type": "integer", "minimum": 0 },
+          "targetBindingChars": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["size", "replenish", "selectSequentially", "selectRandomly", "targetBindingChars"]
+      }
+    },
+    "pools": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "allowedVerbs": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "behaviorProfile": { "type": "string" },
+          "behaviorInline": {
+            "type": "object",
+            "properties": {
+              "size": { "type": "integer", "minimum": 1 },
+              "replenish": { "type": "string", "enum": ["top-up", "replace-all", "consume", "delete-all"] },
+              "selectSequentially": { "type": "integer", "minimum": 0 },
+              "selectRandomly": { "type": "integer", "minimum": 0 },
+              "targetBindingChars": { "type": "integer", "minimum": 0 }
+            },
+            "required": ["size", "replenish", "selectSequentially", "selectRandomly", "targetBindingChars"]
+          },
+          "algo": { "type": "string", "enum": ["SHA-256", "SHA-512"] },
+          "rounds": { "type": "integer", "minimum": 1 },
+          "type": { "type": "string", "enum": ["hash-reveal-v1"] }
+        },
+        "required": ["id", "allowedVerbs", "algo", "rounds"]
+      }
+    }
+  },
+  "required": ["pools"]
+}

package/src/keystone/keystone-service-v1.mts

@@ -256,10 +256,10 @@ export class KeystoneService_V1 {
 
     /**
      * Retrieves the latest keystone frame for the given address.
-     * 
+     *
      * Uses `metaspace.getLatestAddr` to find the actual tip instead of trusting
      * an incoming payload's `past` rel8n.
-     * 
+     *
      * @see `ibgib-get-pattern` SKILL.md
      */
     async getLatestKeystone({
@@ -274,7 +274,7 @@ export class KeystoneService_V1 {
         const lc = `${this.lc}[${this.getLatestKeystone.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting...`); }
-            
+
             const latestAddr = await metaspace.getLatestAddr({ tjpAddr: addr, space });
             if (!latestAddr) {
                 throw new Error(`could not find latest addr for ${addr}`);

package/src/sync/README.md

@@ -20,7 +20,6 @@ Init -> Ack -> Delta(s) -> Conflict/Commit via "ping pong" exchange.
 
 1.  **Init**: Sender initiates sync.
     * Creates the `SyncSagaIbGib_V1` with an `Init` msg frame containing knowledge about domain ibgibs to sync.
-    * Optionally creates session keystone based off of Sender's primary keystone.
     * Wraps the saga ibgib in a `SyncSagaContextIbGib_V1` and passes to the `SyncPeer_V1`.
 2.  **Ack**: Receiver gets incoming `SyncSagaContextIbGib_V1` and passes to its `SyncSagaCoordinator`.
     * Handles the `Init` frame, comparing knowledge with Receiver's own status of each timeline/stone in domain ibgibs.
@@ -34,44 +33,11 @@ Init -> Ack -> Delta(s) -> Conflict/Commit via "ping pong" exchange.
       * `SyncPeer_V1.payloadIbGibsDomainReceived$` is an observable for the actual domain payload ibgibs transmitted.
       * So the a node sends domain payloads out in bulk to the `SyncPeer_V1`, receives the return saga ibgib with a manifest, but may have to wait for the observable to complete to actually process the ibgibs.
     * `Delta` frame can include `requests` (e.g., asking for missing conflict history).
-    * Once no deltas required, `Delta` frame sets `proposeCommit` flag. If the other has nothing to add, the session transitions to `Commit`.
+    * Once no deltas required, `Delta` frame sets `proposeCommit` flag. If the other has nothing to add, the saga transitions to `Commit`.
 4.  **Commit**: When receive `Delta` frame with `proposeCommit`,  should trigger the receiver of this to start its commit. If that is successful, it should return a `Commit` frame, which signals the commit was successful on their end. When this `Commit` frame is received, this end should not perform its own commit.
     * For local-only syncs, the `SyncPeer_V1` implementation is responsible for moving verified `ibGibs` from the temporary saga space to the durable/persistent domain space.
 *   From each endpoint's POV, the cleanup should remove the temp spaces used, in addition to any other required transaction cleanup (like closing any connections).
 
-### Session Identity (`useSessionIdentity`)
-
-The sync protocol can optionally generate an ephemeral Keystone Identity for the duration of the saga.
-
-**Purpose**: To allow secure, signed exchanges even if the Node doesn't have a long-lived identity, or to isolate the sync session security from master identity.
-
-**Current Status**:
-*   ✅ Session keystone creation implemented ([getSessionIdentity()](file:./sync-saga-coordinator.mts#L328-L362))
-*   ✅ Keystone passed via Init message ([initData.identity](file:./sync-saga-message/sync-saga-message-types.mts#L75))
-*   ⚠️ **Signature generation/verification: NOT yet implemented**
-*   ⚠️ **Per-frame proof creation: NOT yet implemented**
-
-**Usage**:
-```typescript
-const { done } = await coordinator.sync({
-  peer,
-  domainIbGibs: [timeline],
-  localSpace,
-  metaspace,
-  useSessionIdentity: true, // Default, but currently non-functional
-});
-```
-
-> [!CAUTION]
-> **🚧 Session identity is NOT working yet.** Tests explicitly set `useSessionIdentity: false` to avoid failures. See [sync-innerspace-dest-ahead-withid.respec.mts](file:./sync-innerspace-dest-ahead-withid.respec.mts) for the failing test case.
-
-**Authentication/Authorization Hooks**:
-
-Validation occurs in [SyncPeer_V1.witness()](file:./sync-peer/sync-peer-v1.mts#L129-L219):
-1. `validateContextAndSagaFrame()` - Intrinsic validation
-2. `authenticateContext()` - Verify identity (stub)
-3. `authorizeContext()` - Check permissions (stub)
-
 ### Conflict Resolution via Grafting
 
 > [!IMPORTANT]
@@ -110,58 +76,6 @@ See [graft-info-helpers.mts](file:./graft-info/graft-info-helpers.mts) for imple
 
 **Why**: Ensures atomic sync - either all data validates and commits, or none does.
 
-
-## 🔒 Security Considerations
-
-> [!WARNING]
-> Session identity is **currently non-functional**. The mitigations below describe the intended security model.
-
-### Attack Vectors & Mitigations
-
-| Attack Vector | Description | Mitigation |
-|---------------|-------------|------------|
-| **MITM Replay** | Attacker replays captured saga frames | • Frame signatures include timestamp<br>• Freshness checks reject old frames<br>• Challenge depletion prevents reuse<br>• sagaId deduplication |
-| **Session Fixation** | Attacker pre-generates session keystone | • Session secret derived via KDF (strategy in keystone metadata)<br>• `sessionSecret = KDF(masterSecret, sagaId, strategy)` |
-| **Identity Spoofing** | Impersonation via fake session keystone | • Session keystone includes `derivedFrom` master address<br>• Receiver validates master keystone is known/trusted |
-| **Challenge Grinding** | Brute-force challenge solutions for target binding | • Hash pre-imaging computationally infeasible<br>• Stochastic selection adds randomness |
-| **DoS (Pool Exhaustion)** | Excessive syncs deplete challenge pools | • Top-up replenishment refills challenges<br>• Rate limiting per identity<br>• Pool separation for critical ops |
-| **Saga Hijacking** | Mid-flight frame injection | • All frames signed with session keystone<br>• `past` rel8n creates tamper-evident chain |
-
-### Cryptographic Primitives
-
-*   **Hash Function**: SHA-256 (content addressing, challenge generation)
-*   **Proof System**: Hash-reveal protocol (`hash-reveal-v1`)
-*   **Binding**: Target address → hex bucket → challenge selection
-*   **Entropy**: Stochastic challenge selection (anti-grinding)
-
-### Trust Model
-
-**Session Keystones**:
-- Ephemeral identity per sync saga
-- Derived from master keystone + `sagaId`
-- Validates via proof-of-work (solving challenges)
-- Post-hoc audit trail: master can prove session authorship
-
-**Propagation**:
-- Sync does NOT rely on global PKI or certificate authorities
-- Trust propagates through sync sessions (Alice syncs with Bob → Bob witnesses Alice's keystone)
-- Revocation propagates same way (Alice revokes → syncs revocation to Bob → Bob sees revoked timeline)
-
-**Threat Boundaries**:
-- ✅ Protects against: MITM replay, impersonation, frame tampering
-- ⚠️ Does NOT protect against: Compromised endpoint (live memory access during active session)
-- ⚠️ Master secrets: Raw secrets should NOT stored; keystones master secrets to keystones should be derived secrets via key stretching passwords. raw secret files of course can drive these passwords and must be protected
-- ⚠️ Transport security: Use TLS for network layer encryption (ibgib protocol provides authentication/integrity, not confidentiality)
-
-### Best Practices
-
-1. **Master Secret Protection**: Store master secrets in secure enclaves/keychains
-2. **Session Lifetime**: Limit saga duration, revoke sessions post-completion
-3. **Rate Limiting**: Implement per-identity sync rate limits
-4. **Freshness**: Reject frames older than 60 seconds
-5. **Audit Logs**: Persist saga timelines for post-hoc validation (saga timelines are ibgibs, so integrity is built-in via content addressing)
-6. **TLS**: Always use TLS for network transport (defense-in-depth)
-
 ## 📚 Documentation
 *   **[Architecture](./docs/architecture.md)**: Detailed design of the Saga Protocol, State Machine, and Smart Diff logic.
 *   **[Testing & Verification](./docs/testing.md)**: Test strategy, verification matrix, and comprehensive testing guidelines.
@@ -175,20 +89,3 @@ See [graft-info-helpers.mts](file:./graft-info/graft-info-helpers.mts) for imple
 ## Verification
 We rely on rigorous In-Memory Simulation (`InnerSpace`) to verify complex graph scenarios. See **[Verification](./docs/verification.md)** for the full status.
 
----
-
-## ❓ Open Questions
-
-### Payload Scope Validation: Can the Protocol Police What ibGibs Are Transmitted?
-
-**Question**: During a sync session authorized by session substone S (itself authorized by domain keystone I with `claim.target = S^Stjp` and sync subject `X^X10.Xtjp`), should the server validate that all Delta payload ibgibs are genuinely related to X's timeline? Or is it sufficient that they arrive under a valid substone?
-
-**Context**: The substone's `frameDetails` records both the parent identity `I^Itjp` and the sync subject `X^X10.Xtjp`. In theory the server could walk the dependency graph of each incoming Delta payload and confirm every ibgib is either:
-- A control ibgib (sync saga, context, substone frames), or
-- Part of the dependency graph rooted at some frame of X's timeline (`X^Xtjp`)
-
-**Problem**: This check may not be enforceable at the protocol layer. A client who controls the keystone (has the master secret) could always evolve X's timeline to hard-link any arbitrary ibgib, and that ibgib would then pass the "is in X's dependency graph" check. So the constraint can be trivially bypassed by the legitimate key-holder, making it only useful against *illegitimate* actors — who are already blocked by the keystone proof requirement.
-
-**Current position**: This is likely a **higher-layer business rule** rather than a sync protocol concern. The sync protocol's job is to ensure the session is cryptographically authorized (via keystone proofs). What is stored under an authorized session is the domain owner's responsibility. Enforcement of content policies (e.g., "only ibgibs of type X are allowed") belongs in the server's `authorizeContext` hook, not in the core sync coordinator.
-
-**Tracked in**: `space-gib.sync-walkthrough.md`

package/src/sync/docs/architecture.md

@@ -21,7 +21,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 ### 2.1 The Ping-Pong Flow
 
 1.  **Start (Initiator)**:
-    *   Initiator (Alice) calls `startSaga`.
+    *   Initiator (Alice) calls `sync`.
     *   Generates `Init` frame containing her `KnowledgeMap` and `Mode` (Push/Pull/Sync).
     *   Sends `Init` to Bob.
 
@@ -42,7 +42,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 
 4.  **Convergence (`handleDeltaFrame`)**:
     *   Bob receives `Delta`.
-    *   **Verifies**: Checks content-address hashes (`ib` vs `gib`). ⚠️ Keystone signature verification pending.
+    *   **Verifies**: Checks content-address hashes.
     *   **Merges**: Puts data into his local space.
     *   Bob sends `Commit` frame.
 
@@ -55,7 +55,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 ### 3.1 SyncSagaMessage
 All frames are `SyncIbGib`s carrying specific data payloads.
 
-*   `sagaId`: Unique UUID for the session.
+*   `sagaId`: Unique UUID for the duration of this exchange.
 *   `stage`: `init` | `ack` | `delta` | `commit` | `conflict`.
 *   `knowledgeMap`: `{ [tjpAddr]: [tipAddr, ...ancestors] }`.
 
@@ -65,8 +65,19 @@ The protocol supports two types of data:
 *   **Stones (Constants)**: Immutable data without a history (e.g., Code lists, Configs). Syncing involves simple existence checks.
 
 ## 4. Security & Identity
-*   **Session Keystone**: Each Saga can optionally generate an ephemeral identity to sign frames, linked to a master identity. ⚠️ **Currently non-functional** - see [README Session Identity section](file:../README.md#session-identity-usesessionidentity) for status.
-*   **Trust Chain**: Each frame points to the previous one (`past` rel8n), creating a hash-linked chain of custody.
+
+See [Security](./security.md) documentation.
+
+### 4.1 Ephemeral Session Domain-Binding
+To prevent an ephemeral session keystone `S` from acting as a "blank check" that could authorize operations on arbitrary timelines, the protocol implements strict domain-binding:
+*   **Genesis Binding**: The first frame of the session keystone ($S^{Stjp}$) must explicitly contain a `targetAddrs` array inside its `frameDetails` mapping to the exact addresses of the ibgibs being synchronized.
+*   **Verification Boundary**: During the initial turn-based synchronization (e.g., `handleInitFrame`), the validating peer (Receiver) must extract this `targetAddrs` array from $S^{Stjp}$'s genesis `frameDetails` and verify it contains the synchronizing domain's target address, rejecting the handshake on any mismatch.
+
+## 5. Sync Peer Lifetime
+
+A `SyncPeer` is **single-saga scoped**. One peer instance services exactly one `sync(...)` call from creation through saga completion. The coordinator's `newTestPeer()` factory pattern (or equivalent in production) must create a fresh peer per saga.
+
+**Rationale**: The session keystone `S` is derived from `KDF(senderSecret, sagaId)`. Since `sagaId` is unique per saga, `S` is inherently saga-bound. A peer that outlived its saga would hold stale identity state, violating the security model.
 
 > [!WARNING]
 > ## 5. Sync Storage & Persistence Rules (Critical Security)
@@ -74,17 +85,26 @@ The protocol supports two types of data:
 > Knowing **when** to put **what** ibgib frames into **which** space is a high-priority security concern. The sync algorithm must balance maintaining a robust audit trail with protecting durable spaces from unauthorized pollution. Always follow these rules:
 >
 > ### Rule 1: Saga/Control Audit Trail (Immediate Persistence)
-> We need an audit trail of the sync saga itself (including context and identity info).
+> We need an audit trail of the sync saga itself (including context and authentication info).
 > * The initial session keystone (or any valid evolution performed locally) and saga control ibgibs are trusted because *we* just generated them.
 > * Persist these immediately in the **local durable space** (and possibly the local temporary space if needed for transit) so they are available for validation and auditing.
 >
 > ### Rule 2: Domain IbGibs (Deferred Persistence)
 > We do NOT persist *any* domain ibgibs (e.g., user payloads) into the durable space before the `commit` phase of the sync process.
-> * Domain ibgibs must be routed to the **tempSpace** during the `delta` or `ack` phases. 
+> * Domain ibgibs must be routed to the **tempSpace** during the `delta` or `ack` phases.
 > * The `commit` phase acts as the transaction boundary. By waiting for the commit, we avoid polluting durable spaces on error, preventing the need for complex rollbacks.
 >
 > ### Rule 3: Validate First, Store Second
 > We never chance storing intrinsically invalid ibgibs.
 > * **First step:** Intrinsically validate ibgibs (hashes, basic structure).
-> * **Second step:** Perform AuthN/AuthZ checks (using the ephemeral session keystone).
+> * **Second step:** Perform AuthN/AuthZ checks (using the session keystone).
 > * **Final step:** Once verified, saga "control" ibgibs (which only contain "soft" links to domain ibgibs) can be safely persisted to durable spaces.
+
+## 6. Transport & Framing (Naive WebSocket Implementation)
+
+> [!NOTE]
+> ### TODO: Robust WebSocket Framing & TCP Reassembly
+> The current custom WebSocket integration on the node server (`ws-helper.mts`) relies on a naive framing implementation. It assumes each socket `data` event emitted by Node's TCP stream contains exactly one complete WebSocket frame.
+> 
+> * **TCP Fragmentation Risk**: When payload sizes grow (e.g. sending larger cryptographic proofs or domain datasets), TCP will split the frame across multiple packets or buffers. The naive decoder will decode a partial frame, causing parse errors (e.g., `Unterminated string in JSON`).
+> * **Future Action**: Replace the custom, naive WebSocket framing code with a robust stateful accumulator that aggregates incoming TCP chunks until the entire frame length (indicated in the frame header) is present in memory, or transition to a fully tested, production-grade library (such as the NPM `ws` package).