@private.me/xbind 1.2.0

package/dist-standalone/checkpoint.d.ts

@@ -0,0 +1,125 @@
+import type { Result } from '@private.me/shared';
+/** Error codes for checkpoint operations. */
+export type CheckpointError = 'SIGN_FAILED' | 'VERIFY_FAILED' | 'INVALID_FORMAT' | 'INVALID_TIMESTAMP' | 'INVALID_SIGNATURE' | 'STALE_CACHE';
+/**
+ * Gateway-signed DID state checkpoint (freshness primitive).
+ *
+ * Checkpoints provide cryptographic proof of DID state at a specific timestamp.
+ * Clients compare checkpoint rotation_sequence against local cache to detect staleness.
+ *
+ * Format:
+ * - subject: DID being checkpointed
+ * - current_public_key: Current public key (base64)
+ * - revoked: Revocation status
+ * - rotation_sequence: Monotonic counter from succession events
+ * - timestamp: Unix milliseconds when checkpoint was created
+ * - checkpoint_signature: ML-DSA-65 signature from gateway key
+ */
+export interface DIDStateCheckpoint {
+    readonly type: 'DIDStateCheckpoint';
+    readonly version: '1.0';
+    readonly subject: string;
+    readonly current_public_key: string;
+    readonly revoked: boolean;
+    readonly rotation_sequence: number;
+    readonly timestamp: number;
+    readonly checkpoint_signature_algorithm: 'ML-DSA-65';
+    readonly checkpoint_signature: string;
+}
+/**
+ * Local cache entry for DID state.
+ * Used for staleness detection against signed checkpoints.
+ */
+export interface LocalDIDCache {
+    readonly did: string;
+    readonly publicKey: Uint8Array;
+    readonly revoked: boolean;
+    readonly rotationSequence: number;
+    readonly cachedAt: number;
+}
+/**
+ * Create a signed checkpoint for a DID (gateway-side operation).
+ *
+ * Gateway signs the DID state snapshot using its ML-DSA-65 private key.
+ * Clients verify this signature using the gateway's published public key.
+ *
+ * @param subject - DID being checkpointed
+ * @param publicKey - Current public key bytes
+ * @param revoked - Current revocation status
+ * @param rotationSequence - Current rotation sequence counter
+ * @param gatewayPrivateKey - Gateway's ML-DSA-65 secret key (32-byte seed or 4032-byte expanded)
+ * @returns Signed checkpoint or error
+ *
+ * @example
+ * ```typescript
+ * const checkpoint = await createCheckpoint(
+ *   'did:key:z6Mk...',
+ *   publicKeyBytes,
+ *   false,
+ *   5,
+ *   gatewaySecretKey
+ * );
+ * if (checkpoint.ok) {
+ *   // Send checkpoint to client for staleness detection
+ *   sendToClient(checkpoint.value);
+ * }
+ * ```
+ */
+export declare function createCheckpoint(subject: string, publicKey: Uint8Array, revoked: boolean, rotationSequence: number, gatewayPrivateKey: Uint8Array): Promise<Result<DIDStateCheckpoint, CheckpointError>>;
+/**
+ * Verify a checkpoint signature (client-side operation).
+ *
+ * Clients MUST verify checkpoint signatures before trusting the state.
+ * Uses gateway's published ML-DSA-65 public key to verify signature.
+ *
+ * @param checkpoint - Checkpoint to verify
+ * @param gatewayPublicKey - Gateway's ML-DSA-65 public key (1952 bytes)
+ * @returns true if signature valid, false if invalid, error if verification fails
+ *
+ * @example
+ * ```typescript
+ * const valid = await verifyCheckpoint(checkpoint, gatewayPubKey);
+ * if (valid.ok && valid.value) {
+ *   // Checkpoint is authentic - safe to use for staleness detection
+ *   if (isCacheStale(localCache, checkpoint)) {
+ *     // Refresh local cache
+ *   }
+ * }
+ * ```
+ */
+export declare function verifyCheckpoint(checkpoint: DIDStateCheckpoint, gatewayPublicKey: Uint8Array): Promise<Result<boolean, CheckpointError>>;
+/**
+ * Detect if local cache is stale compared to gateway checkpoint.
+ *
+ * Cache is stale if:
+ * 1. Checkpoint rotation_sequence > local rotationSequence (key rotated)
+ * 2. Checkpoint revoked !== local revoked (revocation status changed)
+ * 3. Checkpoint public key !== local publicKey (state drift)
+ *
+ * @param localCache - Local cache entry for DID
+ * @param checkpoint - Verified checkpoint from gateway
+ * @returns true if cache needs refresh, false if cache is current
+ *
+ * @example
+ * ```typescript
+ * if (isCacheStale(localCache, checkpoint)) {
+ *   // Local cache is outdated - fetch fresh state from gateway
+ *   const freshState = await registry.getEntry(did);
+ * }
+ * ```
+ */
+export declare function isCacheStale(localCache: LocalDIDCache, checkpoint: DIDStateCheckpoint): boolean;
+/**
+ * Encode checkpoint to JSON string for wire transport.
+ *
+ * @param checkpoint - Checkpoint to encode
+ * @returns JSON string
+ */
+export declare function encodeCheckpoint(checkpoint: DIDStateCheckpoint): string;
+/**
+ * Decode checkpoint from JSON string.
+ *
+ * @param encoded - JSON string
+ * @returns Parsed checkpoint or error
+ */
+export declare function decodeCheckpoint(encoded: string): Result<DIDStateCheckpoint, CheckpointError>;

package/dist-standalone/checkpoint.js

@@ -0,0 +1,186 @@
+import { ok, err } from"./_deps/shared/index.js";
+import { signMlDsa65, verifyMlDsa65 } from './identity.js';
+/* ── Checkpoint Creation (Gateway-side) ── */
+/**
+ * Create a signed checkpoint for a DID (gateway-side operation).
+ *
+ * Gateway signs the DID state snapshot using its ML-DSA-65 private key.
+ * Clients verify this signature using the gateway's published public key.
+ *
+ * @param subject - DID being checkpointed
+ * @param publicKey - Current public key bytes
+ * @param revoked - Current revocation status
+ * @param rotationSequence - Current rotation sequence counter
+ * @param gatewayPrivateKey - Gateway's ML-DSA-65 secret key (32-byte seed or 4032-byte expanded)
+ * @returns Signed checkpoint or error
+ *
+ * @example
+ * ```typescript
+ * const checkpoint = await createCheckpoint(
+ *   'did:key:z6Mk...',
+ *   publicKeyBytes,
+ *   false,
+ *   5,
+ *   gatewaySecretKey
+ * );
+ * if (checkpoint.ok) {
+ *   // Send checkpoint to client for staleness detection
+ *   sendToClient(checkpoint.value);
+ * }
+ * ```
+ */
+export async function createCheckpoint(subject, publicKey, revoked, rotationSequence, gatewayPrivateKey) {
+    const timestamp = Date.now();
+    // Construct canonical message to sign
+    const publicKeyB64 = Buffer.from(publicKey).toString('base64');
+    const message = `DIDStateCheckpoint||1.0||${subject}||${publicKeyB64}||${revoked}||${rotationSequence}||${timestamp}`;
+    const messageBytes = new TextEncoder().encode(message);
+    // Sign using gateway's ML-DSA-65 key
+    const sigResult = await signMlDsa65(gatewayPrivateKey, messageBytes);
+    if (!sigResult.ok) {
+        return err('SIGN_FAILED');
+    }
+    return ok({
+        type: 'DIDStateCheckpoint',
+        version: '1.0',
+        subject,
+        current_public_key: publicKeyB64,
+        revoked,
+        rotation_sequence: rotationSequence,
+        timestamp,
+        checkpoint_signature_algorithm: 'ML-DSA-65',
+        checkpoint_signature: Buffer.from(sigResult.value).toString('base64')
+    });
+}
+/* ── Checkpoint Verification (Client-side) ── */
+/**
+ * Verify a checkpoint signature (client-side operation).
+ *
+ * Clients MUST verify checkpoint signatures before trusting the state.
+ * Uses gateway's published ML-DSA-65 public key to verify signature.
+ *
+ * @param checkpoint - Checkpoint to verify
+ * @param gatewayPublicKey - Gateway's ML-DSA-65 public key (1952 bytes)
+ * @returns true if signature valid, false if invalid, error if verification fails
+ *
+ * @example
+ * ```typescript
+ * const valid = await verifyCheckpoint(checkpoint, gatewayPubKey);
+ * if (valid.ok && valid.value) {
+ *   // Checkpoint is authentic - safe to use for staleness detection
+ *   if (isCacheStale(localCache, checkpoint)) {
+ *     // Refresh local cache
+ *   }
+ * }
+ * ```
+ */
+export async function verifyCheckpoint(checkpoint, gatewayPublicKey) {
+    // Validate checkpoint format
+    if (checkpoint.type !== 'DIDStateCheckpoint') {
+        return err('INVALID_FORMAT');
+    }
+    if (checkpoint.version !== '1.0') {
+        return err('INVALID_FORMAT');
+    }
+    if (!checkpoint.subject || !checkpoint.current_public_key) {
+        return err('INVALID_FORMAT');
+    }
+    if (typeof checkpoint.rotation_sequence !== 'number' || checkpoint.rotation_sequence < 0) {
+        return err('INVALID_FORMAT');
+    }
+    if (typeof checkpoint.timestamp !== 'number' || checkpoint.timestamp <= 0) {
+        return err('INVALID_TIMESTAMP');
+    }
+    if (checkpoint.checkpoint_signature_algorithm !== 'ML-DSA-65') {
+        return err('INVALID_FORMAT');
+    }
+    // Reconstruct canonical message
+    const message = `DIDStateCheckpoint||1.0||${checkpoint.subject}||${checkpoint.current_public_key}||${checkpoint.revoked}||${checkpoint.rotation_sequence}||${checkpoint.timestamp}`;
+    const messageBytes = new TextEncoder().encode(message);
+    // Decode signature
+    let signature;
+    try {
+        signature = Buffer.from(checkpoint.checkpoint_signature, 'base64');
+    }
+    catch {
+        return err('INVALID_SIGNATURE');
+    }
+    // Verify signature using gateway public key
+    const verifyResult = await verifyMlDsa65(gatewayPublicKey, signature, messageBytes);
+    if (!verifyResult.ok) {
+        return err('VERIFY_FAILED');
+    }
+    return ok(verifyResult.value);
+}
+/* ── Staleness Detection ── */
+/**
+ * Detect if local cache is stale compared to gateway checkpoint.
+ *
+ * Cache is stale if:
+ * 1. Checkpoint rotation_sequence > local rotationSequence (key rotated)
+ * 2. Checkpoint revoked !== local revoked (revocation status changed)
+ * 3. Checkpoint public key !== local publicKey (state drift)
+ *
+ * @param localCache - Local cache entry for DID
+ * @param checkpoint - Verified checkpoint from gateway
+ * @returns true if cache needs refresh, false if cache is current
+ *
+ * @example
+ * ```typescript
+ * if (isCacheStale(localCache, checkpoint)) {
+ *   // Local cache is outdated - fetch fresh state from gateway
+ *   const freshState = await registry.getEntry(did);
+ * }
+ * ```
+ */
+export function isCacheStale(localCache, checkpoint) {
+    // Sequence number mismatch indicates key rotation
+    if (checkpoint.rotation_sequence > localCache.rotationSequence) {
+        return true;
+    }
+    // Revocation status changed
+    if (checkpoint.revoked !== localCache.revoked) {
+        return true;
+    }
+    // Public key mismatch indicates state drift
+    const checkpointPubKey = Buffer.from(checkpoint.current_public_key, 'base64');
+    if (!Buffer.from(localCache.publicKey).equals(checkpointPubKey)) {
+        return true;
+    }
+    return false;
+}
+/* ── Encoding/Decoding ── */
+/**
+ * Encode checkpoint to JSON string for wire transport.
+ *
+ * @param checkpoint - Checkpoint to encode
+ * @returns JSON string
+ */
+export function encodeCheckpoint(checkpoint) {
+    return JSON.stringify(checkpoint);
+}
+/**
+ * Decode checkpoint from JSON string.
+ *
+ * @param encoded - JSON string
+ * @returns Parsed checkpoint or error
+ */
+export function decodeCheckpoint(encoded) {
+    try {
+        const parsed = JSON.parse(encoded);
+        // Basic validation
+        if (parsed.type !== 'DIDStateCheckpoint') {
+            return err('INVALID_FORMAT');
+        }
+        if (parsed.version !== '1.0') {
+            return err('INVALID_FORMAT');
+        }
+        if (!parsed.subject || !parsed.current_public_key || !parsed.checkpoint_signature) {
+            return err('INVALID_FORMAT');
+        }
+        return ok(parsed);
+    }
+    catch {
+        return err('INVALID_FORMAT');
+    }
+}