@xnetjs/sync 0.12.0 → 2.0.0

package/dist/index.d.ts

@@ -14,12 +14,18 @@ import { PQKeyRegistry, HybridKeyBundle } from '@xnetjs/identity';
  * Current protocol version for Change<T>.
  *
  * Version history:
- * - 3: Multi-level cryptography with hybrid signatures (Ed25519 + ML-DSA)
+ * - 4: Grinding-resistant LWW tiebreak key (exploration 0300). NOTE: the change
+ *   signature is still **Ed25519-only** — `signChange`/`verifyChange` use the
+ *   classical `@xnetjs/crypto` `sign`/`verify`. The hybrid/ML-DSA apparatus
+ *   (`hybrid-signing.ts`) is NOT wired into `Change<T>` yet; wiring it (or the
+ *   PQ envelope) is tracked in exploration 0307.
+ * - 3: Reserved for multi-level cryptography (hybrid Ed25519 + ML-DSA) — defined
+ *   in the crypto layer but not carried by the change-signing path.
  * - 2: V2 compact format with abbreviated field names
  * - 1: Initial versioned protocol (adds protocolVersion field)
  * - 0/undefined: Legacy unversioned changes (backward compat)
  */
-declare const CURRENT_PROTOCOL_VERSION = 3;
+declare const CURRENT_PROTOCOL_VERSION = 4;
 /**
  * A signed change with chain linkage and Lamport ordering.
  * Generic T allows different payload types for different use cases:
@@ -320,6 +326,13 @@ interface Fork<T = unknown> {
  * - All hashes are computed correctly (not tampered)
  * - Parent references exist in the chain (or are null for roots)
  *
+ * SECURITY: this is a **structural** check only — it does NOT verify Ed25519
+ * signatures, and a missing parent or a fork is reported (or tolerated) rather
+ * than treated as a hard failure. It is not an admission gate for untrusted
+ * input: authenticate authorship with `verifyChange` (and apply LWW/idempotency)
+ * at the ingest boundary — see `NodeStore.applyRemoteChange` and the hub's
+ * `node-relay.ts`, which run the real crypto checks (exploration 0307).
+ *
  * @param changes - The changes to validate
  * @returns Validation result
  */
@@ -1923,7 +1936,7 @@ interface AuthorizedYjsSyncProviderOptions<TDoc extends YDocLike = YDocLike> {
     verifyEnvelope?: (envelope: SignedYjsEnvelopeV2) => Promise<EnvelopeVerificationResult>;
     onRejected?: (input: {
         peerId: DID;
-        reason: 'rate-exceeded' | 'invalid-signature' | 'unauthorized';
+        reason: 'rate-exceeded' | 'oversized' | 'invalid-signature' | 'unauthorized';
     }) => void;
 }
 declare class AuthorizedYjsSyncProvider<TDoc extends YDocLike = YDocLike> {
@@ -1936,6 +1949,16 @@ declare class AuthorizedYjsSyncProvider<TDoc extends YDocLike = YDocLike> {
     private readonly verifyEnvelope;
     private readonly onRejected?;
     constructor(options: AuthorizedYjsSyncProviderOptions<TDoc>);
+    /**
+     * Admit a remote Yjs update: rate-limit → size cap → signature → authz →
+     * doc-binding, then apply.
+     *
+     * SECURITY (exploration 0307): the peer scorer here is **advisory** — it
+     * accumulates violation penalties but this method does not itself refuse an
+     * already-blocked peer; wire `YjsPeerScorer.getPeerAction`/`onAction` to a
+     * transport that actually drops blocked peers. The size cap below and the
+     * signature/authz/doc-binding checks are the hard gates.
+     */
     handleRemoteUpdate(envelope: SignedYjsEnvelopeV2): Promise<boolean>;
 }
 declare class AuthorizedYjsError extends Error {
@@ -2038,6 +2061,14 @@ interface VerifyAttestationOptions {
     registry?: PQKeyRegistry;
     /** Minimum security level required */
     minLevel?: SecurityLevel;
+    /**
+     * Reject an attestation whose `clientId` is not the value derived from its
+     * DID ({@link deriveClientIdFromDid}) — exploration 0305. Constrains the Yjs
+     * clientID so a client cannot pick a maximal one to win insert races. Default
+     * `false` for backward compatibility with pre-0305 random clientIDs; xNet's
+     * own verification path enables it once clients derive their clientID.
+     */
+    enforceDerivedClientId?: boolean;
 }
 /**
  * Check if an attestation is V2 format.
@@ -2047,6 +2078,23 @@ declare function isV2Attestation(attestation: ClientIdAttestation): attestation
  * Check if an attestation is V1 format.
  */
 declare function isV1Attestation(attestation: ClientIdAttestation): attestation is ClientIdAttestationV1;
+/**
+ * Derive a Yjs `clientID` deterministically from a DID (exploration 0305).
+ *
+ * Yjs assigns a *random* integer clientID and breaks concurrent same-position
+ * insert ties by *higher clientID*, so a client is free to pick
+ * `clientID = 0x7FFFFFFF` and win every insert race. Deriving the clientID from
+ * the DID removes that free choice: the value is now a random-oracle function of
+ * identity, so a client cannot pick a maximal one without grinding a whole
+ * keypair (and even then it wins no *durable* advantage — see the LWW tiebreak
+ * key, `@xnetjs/core`).
+ *
+ * Returns a positive 31-bit integer (1 … 2^31−1) — comfortably inside Yjs's
+ * clientID range and never zero (Yjs treats 0 as unset in some paths).
+ */
+declare function deriveClientIdFromDid(did: string): number;
+/** Whether a clientID is the one derived from `did` (exploration 0305). */
+declare function isDerivedClientId(clientId: number, did: string): boolean;
 /**
  * Create a signed clientID attestation (V1 format).
  *
@@ -2814,6 +2862,12 @@ declare class ChangeHandlerRegistry {
 declare const changeHandlerRegistry: ChangeHandlerRegistry;
 /**
  * Create a simple handler that accepts all versions.
+ *
+ * SECURITY: the handler pipeline does NOT verify change hashes or signatures,
+ * and the default `validate` accepts everything. Handlers process
+ * already-authenticated changes — callers MUST verify authorship (`verifyChange`
+ * + `verifyChangeHash`) before routing untrusted input through the registry
+ * (exploration 0307).
  */
 declare function createHandler<T>(type: string, process: (change: Change<T>, context: HandlerContext) => Promise<void>, validate?: (change: Change<T>) => ValidationResult): ChangeHandler<T>;
 /**
@@ -2974,6 +3028,14 @@ interface VerifyOptions {
     maxFutureTimestamp?: number;
     /** Progress callback */
     onProgress?: (checked: number, total: number) => void;
+    /**
+     * Resolve an author DID to its Ed25519 public key so signatures can be
+     * verified cryptographically (not merely checked for presence). Defaults to
+     * {@link parseDID} — a `did:key` is self-certifying (the DID *is* the public
+     * key), so no external key lookup is needed. Provide a custom resolver only
+     * for non-`did:key` identities.
+     */
+    resolveKey?: (did: string) => Uint8Array;
 }
 /**
  * Verify the integrity of a set of changes.
@@ -2987,8 +3049,10 @@ interface VerifyOptions {
  */
 declare function verifyIntegrity(changes: Change<unknown>[], options?: VerifyOptions): Promise<IntegrityReport>;
 /**
- * Quick integrity check - only verifies hashes, not signatures.
- * Much faster but less thorough.
+ * Quick integrity check — verifies **hashes and chain only**, skipping
+ * signature verification. Faster, but it does NOT authenticate authorship, so
+ * a change with a forged signature and a self-consistent hash passes. Use the
+ * full {@link verifyIntegrity} (default) when authorship matters.
  */
 declare function quickIntegrityCheck(changes: Change<unknown>[]): Promise<IntegrityReport>;
 /**
@@ -3014,11 +3078,28 @@ declare function findHeads(changes: Change<unknown>[]): Change<unknown>[];
  * Get the chain depth (longest path from any root to any head).
  */
 declare function getChainDepth(changes: Change<unknown>[]): number;
+/**
+ * Options controlling {@link attemptRepair}.
+ */
+interface RepairOptions {
+    /**
+     * Allow the `recompute-hash` repair, which **overwrites** a change's stored
+     * hash with a freshly computed one. On tampered data this silently reconciles
+     * the tampered payload to a consistent hash (laundering it) rather than
+     * rejecting it, so it is refused unless the caller explicitly asserts the
+     * changes come from a trusted source (e.g. local self-repair, never untrusted
+     * peer input) — exploration 0307. Default: `false`.
+     */
+    trustHashRecompute?: boolean;
+}
 /**
  * Attempt to repair issues that can be fixed automatically.
  * Returns the repaired changes and any issues that couldn't be fixed.
+ *
+ * SECURITY: `recompute-hash` is gated behind {@link RepairOptions.trustHashRecompute}
+ * — do not enable it for changes received from untrusted peers.
  */
-declare function attemptRepair(changes: Change<unknown>[], issues: IntegrityIssue[]): Promise<{
+declare function attemptRepair(changes: Change<unknown>[], issues: IntegrityIssue[], options?: RepairOptions): Promise<{
     repaired: Change<unknown>[];
     remainingIssues: IntegrityIssue[];
     repairCount: number;
@@ -3407,4 +3488,4 @@ declare function createSecurityPolicy(options?: Partial<SecurityPolicy>): Securi
  */
 declare function mergeSecurityPolicies(...policies: Partial<SecurityPolicy>[]): SecurityPolicy;
 
-export { ALL_FEATURES, type AttestationVerificationResult, type AttestationVerifyResult, type AuthorizedDoc, type AuthorizedRoom, type AuthorizedStateAdapter, AuthorizedSyncManager, type AuthorizedSyncManagerOptions, AuthorizedYjsError, AuthorizedYjsSyncProvider, type AuthorizedYjsSyncProviderOptions, BaseSyncProvider, type BatchFlushCallback, COMPACTION_TIME_THRESHOLD, COMPACTION_UPDATE_THRESHOLD, CURRENT_PROTOCOL_VERSION, type ChainValidationResult, type Change, type ChangeHandler, ChangeHandlerRegistry, type ChangeSerializer, type ChangeSigner, type ClientIdAttestation, type ClientIdAttestationV1, type ClientIdAttestationV2, type ClientIdAttestationWire, type ClientIdMap, ClientIdMapImpl, type ContentKeyProvider, type CreateAttestationOptions, type CreateChangeOptions, type CreateEnvelopeOptions, type CreateYjsChangeOptions, DEFAULT_BATCHER_CONFIG, DEFAULT_RATE_LIMITER_CONFIG, DEFAULT_SECURITY_POLICY, DEFAULT_YJS_SCORING_CONFIG, DEPRECATIONS, DEPRECATION_POLICY, type DeprecationCallback, type DeprecationContext, DeprecationError, type DeprecationNotice, type DeprecationType, type DeprecationWarning, type DeserializeError, type DeserializeOutcome, type DeserializeResult, type EncryptedYjsState, type EnvelopeVerificationResult, type EnvelopeVerifyResult, FEATURES, type FeatureConfig, type FeatureFlag, type FeatureValidationError, type FeatureValidationResult, type FeatureValidationWarning, type Fork, type GrantEventStore, HYBRID_SECURITY_POLICY, type HandlerContext, type HandlerEvent, type IntegrityIssue, type IntegrityIssueType, type IntegrityMonitor, type IntegrityMonitorConfig, type IntegrityMonitorStats, type IntegrityReport, type LamportClock, type LamportTimestamp, MAX_SECURITY_POLICY, MAX_YJS_AWARENESS_UPDATE_SIZE, MAX_YJS_DOC_SIZE, MAX_YJS_STATE_VECTOR_SIZE, MAX_YJS_UPDATES_PER_MINUTE, MAX_YJS_UPDATES_PER_SECOND, MAX_YJS_UPDATE_SIZE, type MergeUpdatesFn, type NegotiatedSession, type NegotiationFailure, type NegotiationResult, type NegotiationWarning, type OperationType, type PeerAction, type PeerCapabilities, type PeerInfo, type PersistedDocState, type PolicyRevisionSimulation, type ProcessResult, type RateLimiterConfig, type ReactIntegrityMonitorOptions, type RecipientKeyResolver, type RegistryStats, type RepairAction, type RepairActionType, type ReplicationNamespaceKind, type ReplicationPlan, type ReplicationPlanDestination, type ReplicationPlanDiagnostic, type ReplicationPlanTraceStep, type ResolvedSyncReplicationPolicy, type SecurityPolicy, type SerializeOptions, type SerializedChange, type SerializerRegistry, type SignedYjsEnvelope, type SignedYjsEnvelopeV1, type SignedYjsEnvelopeV2, type SignedYjsEnvelopeWire, type SyncCompatibilityConfig, type SyncConnectionStatus, type SyncEventListener, type SyncFederationConfig, type SyncFederationHub, type SyncFederationNamespacePolicy, type SyncLifecycleInput, type SyncLifecyclePhase, type SyncLifecycleState, type SyncProvider, type SyncProviderEvents, type SyncProviderOptions, type SyncReplicationConfig, type SyncStatus, type UnsignedChange, type UnsignedYjsChange, V1Serializer, V2Serializer, type ValidationError, type ValidationResult, type ValidationWarning, type VerifyAttestationOptions, type VerifyEnvelopeOptions, type VerifyOptions, VersionNegotiator, type YDocCodec, type YDocLike, YJS_CHANGE_TYPE, YJS_RATE_BURST_ALLOWANCE, YJS_SYNC_CHUNK_SIZE, type YjsAuthDecision, YjsAuthGate, type YjsAuthGateOptions, YjsBatcher, type YjsBatcherConfig, type YjsChange, YjsCheckpointer, type YjsCheckpointerOptions, YjsIntegrityError, type YjsPeerActionEvent, type YjsPeerActionListener, type YjsPeerMetrics, YjsPeerScorer, YjsRateLimiter, type YjsRateLimiterOptions, type YjsScoringConfig, YjsStateIntegrityError, type YjsUpdatePayload, type YjsViolationType, addDependencies, attemptRepair, autoDeserialize, autoSerialize, calculateChunkCount, changeHandlerRegistry, checkAndLogDeprecations, checkDeprecations, chunkUpdate, clearLoggedDeprecations, compareLamportTimestamps, computeChangeHash, configureDeprecationPolicy, createBatchId, createChangeId, createClientIdAttestation, createClientIdAttestationV1, createClientIdAttestationV2, createHandler, createIntegrityMonitor, createLamportClock, createLocalCapabilities, createPersistedDocState, createReactIntegrityMonitor, createSecurityPolicy, createSerializerRegistry, createSyncLifecycleState, createTestContext, createUnsignedChange, createUnsignedYjsChange, createVersionedHandler, createWebCryptoChangeSigner, createYjsChange, decryptYjsState, defaultNegotiator, deriveSyncLifecyclePhase, deserializeClientIdAttestation, deserializeEncryptedYjsState, deserializeYjsEnvelope, detectFork, diffFeatures, encryptYjsState, envelopeSize, estimateBase64DecodedLength, findCommonAncestor, findHeads, findOrphans, findRoots, formatDeprecationReport, formatIntegrityReport, getAllDependencies, getAncestry, getChainDepth, getChainHeads, getChainRoots, getChangeNodeId, getDefaultSerializer, getDeprecation, getDeprecationsByType, getEnabledFeatures, getFeatureConflicts, getFeatureDependencies, getFeatureVersion, getForks, getOptionalFeatures, getRequiredFeatures, getSecurityLevel, getSerializer, hasSignedEnvelope, hashYjsState, inferReplicationNamespaceKind, intersectFeatures, isAfter, isAwarenessUpdateTooLarge, isBase64PayloadTooLarge, isBefore, isCriticalOperation, isDeprecated, isDocumentTooLarge, isEphemeralOperation, isFeatureAvailable, isFeatureEnabled, isLegacyUpdate, isNodeChange, isRemoved, isStateVectorTooLarge, isUpdateTooLarge, isV1Attestation, isV1Envelope, isV2Attestation, isV2Envelope, isYjsChange, loadVerifiedState, logDeprecation, maxTime, mergeSecurityPolicies, normalizeSyncFederationHubs, parseCapabilities, parseTimestamp, planReplicationDestinations, quickIntegrityCheck, reassembleChunks, receive, recomputeChangeHash, registerDeprecation, resolveSyncReplicationPolicy, serializeClientIdAttestation, serializeEncryptedYjsState, serializeTimestamp, serializeYjsEnvelope, serializerRegistry, shouldCompact, signChange, signYjsUpdate, signYjsUpdateBatch, signYjsUpdateV1, signYjsUpdateV2, simulateSyncPolicyRevision, tick, toEncryptedData, topologicalSort, v1Serializer, v2Serializer, validateChain, validateClientIdOwnership, validateFeatureSet, verifyChange, verifyChangeHash, verifyClientIdAttestation, verifyClientIdAttestationV1, verifyClientIdAttestationV2, verifyIntegrity, verifyPersistedDocState, verifySingleChange, verifyYjsEnvelope, verifyYjsEnvelopeQuick, verifyYjsEnvelopeV1, verifyYjsEnvelopeV2, verifyYjsStateIntegrity };
+export { ALL_FEATURES, type AttestationVerificationResult, type AttestationVerifyResult, type AuthorizedDoc, type AuthorizedRoom, type AuthorizedStateAdapter, AuthorizedSyncManager, type AuthorizedSyncManagerOptions, AuthorizedYjsError, AuthorizedYjsSyncProvider, type AuthorizedYjsSyncProviderOptions, BaseSyncProvider, type BatchFlushCallback, COMPACTION_TIME_THRESHOLD, COMPACTION_UPDATE_THRESHOLD, CURRENT_PROTOCOL_VERSION, type ChainValidationResult, type Change, type ChangeHandler, ChangeHandlerRegistry, type ChangeSerializer, type ChangeSigner, type ClientIdAttestation, type ClientIdAttestationV1, type ClientIdAttestationV2, type ClientIdAttestationWire, type ClientIdMap, ClientIdMapImpl, type ContentKeyProvider, type CreateAttestationOptions, type CreateChangeOptions, type CreateEnvelopeOptions, type CreateYjsChangeOptions, DEFAULT_BATCHER_CONFIG, DEFAULT_RATE_LIMITER_CONFIG, DEFAULT_SECURITY_POLICY, DEFAULT_YJS_SCORING_CONFIG, DEPRECATIONS, DEPRECATION_POLICY, type DeprecationCallback, type DeprecationContext, DeprecationError, type DeprecationNotice, type DeprecationType, type DeprecationWarning, type DeserializeError, type DeserializeOutcome, type DeserializeResult, type EncryptedYjsState, type EnvelopeVerificationResult, type EnvelopeVerifyResult, FEATURES, type FeatureConfig, type FeatureFlag, type FeatureValidationError, type FeatureValidationResult, type FeatureValidationWarning, type Fork, type GrantEventStore, HYBRID_SECURITY_POLICY, type HandlerContext, type HandlerEvent, type IntegrityIssue, type IntegrityIssueType, type IntegrityMonitor, type IntegrityMonitorConfig, type IntegrityMonitorStats, type IntegrityReport, type LamportClock, type LamportTimestamp, MAX_SECURITY_POLICY, MAX_YJS_AWARENESS_UPDATE_SIZE, MAX_YJS_DOC_SIZE, MAX_YJS_STATE_VECTOR_SIZE, MAX_YJS_UPDATES_PER_MINUTE, MAX_YJS_UPDATES_PER_SECOND, MAX_YJS_UPDATE_SIZE, type MergeUpdatesFn, type NegotiatedSession, type NegotiationFailure, type NegotiationResult, type NegotiationWarning, type OperationType, type PeerAction, type PeerCapabilities, type PeerInfo, type PersistedDocState, type PolicyRevisionSimulation, type ProcessResult, type RateLimiterConfig, type ReactIntegrityMonitorOptions, type RecipientKeyResolver, type RegistryStats, type RepairAction, type RepairActionType, type ReplicationNamespaceKind, type ReplicationPlan, type ReplicationPlanDestination, type ReplicationPlanDiagnostic, type ReplicationPlanTraceStep, type ResolvedSyncReplicationPolicy, type SecurityPolicy, type SerializeOptions, type SerializedChange, type SerializerRegistry, type SignedYjsEnvelope, type SignedYjsEnvelopeV1, type SignedYjsEnvelopeV2, type SignedYjsEnvelopeWire, type SyncCompatibilityConfig, type SyncConnectionStatus, type SyncEventListener, type SyncFederationConfig, type SyncFederationHub, type SyncFederationNamespacePolicy, type SyncLifecycleInput, type SyncLifecyclePhase, type SyncLifecycleState, type SyncProvider, type SyncProviderEvents, type SyncProviderOptions, type SyncReplicationConfig, type SyncStatus, type UnsignedChange, type UnsignedYjsChange, V1Serializer, V2Serializer, type ValidationError, type ValidationResult, type ValidationWarning, type VerifyAttestationOptions, type VerifyEnvelopeOptions, type VerifyOptions, VersionNegotiator, type YDocCodec, type YDocLike, YJS_CHANGE_TYPE, YJS_RATE_BURST_ALLOWANCE, YJS_SYNC_CHUNK_SIZE, type YjsAuthDecision, YjsAuthGate, type YjsAuthGateOptions, YjsBatcher, type YjsBatcherConfig, type YjsChange, YjsCheckpointer, type YjsCheckpointerOptions, YjsIntegrityError, type YjsPeerActionEvent, type YjsPeerActionListener, type YjsPeerMetrics, YjsPeerScorer, YjsRateLimiter, type YjsRateLimiterOptions, type YjsScoringConfig, YjsStateIntegrityError, type YjsUpdatePayload, type YjsViolationType, addDependencies, attemptRepair, autoDeserialize, autoSerialize, calculateChunkCount, changeHandlerRegistry, checkAndLogDeprecations, checkDeprecations, chunkUpdate, clearLoggedDeprecations, compareLamportTimestamps, computeChangeHash, configureDeprecationPolicy, createBatchId, createChangeId, createClientIdAttestation, createClientIdAttestationV1, createClientIdAttestationV2, createHandler, createIntegrityMonitor, createLamportClock, createLocalCapabilities, createPersistedDocState, createReactIntegrityMonitor, createSecurityPolicy, createSerializerRegistry, createSyncLifecycleState, createTestContext, createUnsignedChange, createUnsignedYjsChange, createVersionedHandler, createWebCryptoChangeSigner, createYjsChange, decryptYjsState, defaultNegotiator, deriveClientIdFromDid, deriveSyncLifecyclePhase, deserializeClientIdAttestation, deserializeEncryptedYjsState, deserializeYjsEnvelope, detectFork, diffFeatures, encryptYjsState, envelopeSize, estimateBase64DecodedLength, findCommonAncestor, findHeads, findOrphans, findRoots, formatDeprecationReport, formatIntegrityReport, getAllDependencies, getAncestry, getChainDepth, getChainHeads, getChainRoots, getChangeNodeId, getDefaultSerializer, getDeprecation, getDeprecationsByType, getEnabledFeatures, getFeatureConflicts, getFeatureDependencies, getFeatureVersion, getForks, getOptionalFeatures, getRequiredFeatures, getSecurityLevel, getSerializer, hasSignedEnvelope, hashYjsState, inferReplicationNamespaceKind, intersectFeatures, isAfter, isAwarenessUpdateTooLarge, isBase64PayloadTooLarge, isBefore, isCriticalOperation, isDeprecated, isDerivedClientId, isDocumentTooLarge, isEphemeralOperation, isFeatureAvailable, isFeatureEnabled, isLegacyUpdate, isNodeChange, isRemoved, isStateVectorTooLarge, isUpdateTooLarge, isV1Attestation, isV1Envelope, isV2Attestation, isV2Envelope, isYjsChange, loadVerifiedState, logDeprecation, maxTime, mergeSecurityPolicies, normalizeSyncFederationHubs, parseCapabilities, parseTimestamp, planReplicationDestinations, quickIntegrityCheck, reassembleChunks, receive, recomputeChangeHash, registerDeprecation, resolveSyncReplicationPolicy, serializeClientIdAttestation, serializeEncryptedYjsState, serializeTimestamp, serializeYjsEnvelope, serializerRegistry, shouldCompact, signChange, signYjsUpdate, signYjsUpdateBatch, signYjsUpdateV1, signYjsUpdateV2, simulateSyncPolicyRevision, tick, toEncryptedData, topologicalSort, v1Serializer, v2Serializer, validateChain, validateClientIdOwnership, validateFeatureSet, verifyChange, verifyChangeHash, verifyClientIdAttestation, verifyClientIdAttestationV1, verifyClientIdAttestationV2, verifyIntegrity, verifyPersistedDocState, verifySingleChange, verifyYjsEnvelope, verifyYjsEnvelopeQuick, verifyYjsEnvelopeV1, verifyYjsEnvelopeV2, verifyYjsStateIntegrity };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/change.ts
 import { hashHex, sign, verify } from "@xnetjs/crypto";
-var CURRENT_PROTOCOL_VERSION = 3;
+var CURRENT_PROTOCOL_VERSION = 4;
 function createUnsignedChange(options) {
   const unsigned = {
     protocolVersion: CURRENT_PROTOCOL_VERSION,
@@ -443,6 +443,9 @@ var FEATURES = {
     required: false,
     description: "Compressed change payloads for bandwidth efficiency"
   }
+  // NOTE: the protocol-v4 grinding-resistant LWW tiebreak (exploration 0305) is
+  // NOT a negotiated feature flag — it is a convergence rule gated purely on a
+  // change's `protocolVersion >= 4` (see `@xnetjs/core`'s compareLwwStamps).
 };
 var ALL_FEATURES = Object.keys(FEATURES);
 function getEnabledFeatures(protocolVersion) {
@@ -2049,6 +2052,16 @@ var AuthorizedYjsSyncProvider = class {
     this.verifyEnvelope = options.verifyEnvelope ?? verifyYjsEnvelopeV2;
     this.onRejected = options.onRejected;
   }
+  /**
+   * Admit a remote Yjs update: rate-limit → size cap → signature → authz →
+   * doc-binding, then apply.
+   *
+   * SECURITY (exploration 0307): the peer scorer here is **advisory** — it
+   * accumulates violation penalties but this method does not itself refuse an
+   * already-blocked peer; wire `YjsPeerScorer.getPeerAction`/`onAction` to a
+   * transport that actually drops blocked peers. The size cap below and the
+   * signature/authz/doc-binding checks are the hard gates.
+   */
   async handleRemoteUpdate(envelope) {
     const peerId = envelope.meta.authorDID;
     if (this.rateLimiter && !this.rateLimiter.allow(peerId)) {
@@ -2056,6 +2069,11 @@ var AuthorizedYjsSyncProvider = class {
       this.onRejected?.({ peerId, reason: "rate-exceeded" });
       return false;
     }
+    if (isUpdateTooLarge(envelope.update)) {
+      this.peerScorer.penalize(peerId, "oversizedUpdate");
+      this.onRejected?.({ peerId, reason: "oversized" });
+      return false;
+    }
     const sigResult = await this.verifyEnvelope(envelope);
     if (!sigResult.valid) {
       this.peerScorer.penalize(peerId, "invalidSignature");
@@ -2110,6 +2128,15 @@ function isV2Attestation(attestation) {
 function isV1Attestation(attestation) {
   return !("v" in attestation);
 }
+function deriveClientIdFromDid(did) {
+  const digest = hash3(new TextEncoder().encode(`xnet-clientid:${did}`), "blake3");
+  const view = new DataView(digest.buffer, digest.byteOffset, digest.byteLength);
+  const value = view.getUint32(0, false) & 2147483647;
+  return value === 0 ? 1 : value;
+}
+function isDerivedClientId(clientId, did) {
+  return clientId === deriveClientIdFromDid(did);
+}
 function attestationPayloadV1(clientId, did, room, expiresAt) {
   const text = `clientid-bind:${clientId}:${did}:${room}:${expiresAt}`;
   return new TextEncoder().encode(text);
@@ -2177,12 +2204,17 @@ function createClientIdAttestationV2(clientId, room, keyBundle, options = {}) {
   };
 }
 async function verifyClientIdAttestationV2(attestation, options = {}) {
-  const { registry, minLevel = 0 } = options;
+  const { registry, minLevel = 0, enforceDerivedClientId = false } = options;
   const errors = [];
   const expired = attestation.expiresAt !== void 0 && Date.now() > attestation.expiresAt;
   if (expired) {
     errors.push("Attestation has expired");
   }
+  if (enforceDerivedClientId && !isDerivedClientId(attestation.clientId, attestation.did)) {
+    errors.push(
+      `clientId ${attestation.clientId} is not derived from the DID (expected ${deriveClientIdFromDid(attestation.did)})`
+    );
+  }
   if (attestation.signature.level < minLevel) {
     errors.push(
       `Security level too low: ${attestation.signature.level} < ${minLevel} (required minimum)`
@@ -2798,7 +2830,7 @@ var V3Serializer = class {
       throw new Error("Invalid signature type in change");
     }
     const wire = {
-      v: 3,
+      v: this.version,
       i: change.id,
       t: change.type,
       p: change.payload,
@@ -2825,10 +2857,10 @@ var V3Serializer = class {
       } else {
         wire = data;
       }
-      if (wire.v !== 3) {
+      if (wire.v !== this.version) {
         return {
           success: false,
-          error: `Expected v3 format, got v${wire.v}. Clear your database and start fresh.`,
+          error: `Expected v${this.version} format, got v${wire.v}. Clear your database and start fresh.`,
           rawData: data
         };
       }
@@ -2855,7 +2887,7 @@ var V3Serializer = class {
       }
       const signature = decodeSignature3(wire.sig);
       const change = {
-        protocolVersion: 3,
+        protocolVersion: this.version,
         id: wire.i,
         type: wire.t,
         payload: wire.p,
@@ -2886,7 +2918,7 @@ var V3Serializer = class {
       return false;
     }
     const obj = data;
-    return obj.v === 3 && typeof obj.i === "string" && typeof obj.t === "string" && typeof obj.sig === "object" && obj.sig !== null;
+    return obj.v === this.version && typeof obj.i === "string" && typeof obj.t === "string" && typeof obj.sig === "object" && obj.sig !== null;
   }
   /**
    * Add schema version to a payload.
@@ -2913,6 +2945,13 @@ var V3Serializer = class {
 };
 var v3Serializer = new V3Serializer();
 
+// src/serializers/v4.ts
+var V4Serializer = class extends V3Serializer {
+  version = 4;
+  name = "V4 Serializer (v3 wire + grinding-resistant LWW tiebreak)";
+};
+var v4Serializer = new V4Serializer();
+
 // src/serializers/index.ts
 var DefaultSerializerRegistry = class {
   serializers = /* @__PURE__ */ new Map();
@@ -2922,6 +2961,7 @@ var DefaultSerializerRegistry = class {
     this.register(v1Serializer);
     this.register(v2Serializer);
     this.register(v3Serializer);
+    this.register(v4Serializer);
   }
   get(version) {
     return this.serializers.get(version);
@@ -3145,6 +3185,7 @@ function createTestContext(overrides) {
 }
 
 // src/integrity.ts
+import { parseDID as parseDID3 } from "@xnetjs/identity";
 async function verifyIntegrity(changes, options = {}) {
   const startTime = Date.now();
   const issues = [];
@@ -3211,6 +3252,24 @@ async function verifyIntegrity(changes, options = {}) {
           // No automatic repair - would need original signing key
         });
         hasIssue = true;
+      } else {
+        const resolveKey = options.resolveKey ?? parseDID3;
+        let signatureValid = false;
+        try {
+          signatureValid = verifyChange(change, resolveKey(change.authorDID));
+        } catch {
+          signatureValid = false;
+        }
+        if (!signatureValid) {
+          issues.push({
+            changeId: change.id,
+            type: "signature-invalid",
+            details: "Signature does not verify against the author DID",
+            severity: "error"
+            // No automatic repair - would need original signing key
+          });
+          hasIssue = true;
+        }
       }
     }
     if (!options.skipChain && change.parentHash !== null) {
@@ -3327,7 +3386,7 @@ function getChainDepth(changes) {
   }
   return getDepth(null);
 }
-async function attemptRepair(changes, issues) {
+async function attemptRepair(changes, issues, options = {}) {
   const changeMap = new Map(changes.map((c) => [c.id, { ...c }]));
   const remainingIssues = [];
   let repairCount = 0;
@@ -3343,6 +3402,10 @@ async function attemptRepair(changes, issues) {
     }
     switch (issue.repairAction.type) {
       case "recompute-hash":
+        if (!options.trustHashRecompute) {
+          remainingIssues.push(issue);
+          break;
+        }
         change.hash = await computeChangeHash(change);
         repairCount++;
         break;
@@ -3915,6 +3978,7 @@ export {
   createYjsChange,
   decryptYjsState,
   defaultNegotiator,
+  deriveClientIdFromDid,
   deriveSyncLifecyclePhase,
   deserializeClientIdAttestation,
   deserializeEncryptedYjsState,
@@ -3958,6 +4022,7 @@ export {
   isBefore,
   isCriticalOperation,
   isDeprecated,
+  isDerivedClientId,
   isDocumentTooLarge,
   isEphemeralOperation,
   isFeatureAvailable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/sync",
-  "version": "0.12.0",
+  "version": "2.0.0",
   "description": "Unified sync primitives for xNet (Change<T>, vector clocks, hash chains)",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,9 @@
     "provenance": true
   },
   "dependencies": {
-    "@xnetjs/core": "0.12.0",
-    "@xnetjs/crypto": "0.12.0",
-    "@xnetjs/identity": "0.12.0"
+    "@xnetjs/core": "2.0.0",
+    "@xnetjs/crypto": "2.0.0",
+    "@xnetjs/identity": "2.0.0"
   },
   "devDependencies": {
     "fast-check": "^4.8.0",