private-gateway-and-kms.md

sequenceDiagram
    participant User
    participant KMSAdapter as KMS Crypto Adapter
    participant SymCrypto as Symmetric Crypto<br/>(AES-CTR)
    participant Gateway as Private Gateway<br/>(private.storacha.link)
    participant KMS as Google Cloud KMS
    participant Storage as IPFS Storage<br/>(w3s.link)

    Note over User,Storage: ENCRYPTION FLOW

    User->>KMSAdapter: uploadEncryptedFile(file)
    
    rect rgb(240, 248, 255)
        Note over KMSAdapter,SymCrypto: File Encryption (Local)
        KMSAdapter->>SymCrypto: encryptStream(file)
        SymCrypto-->>KMSAdapter: {key, iv, encryptedStream}
    end

    rect rgb(255, 248, 240)
        Note over KMSAdapter,KMS: Key Encryption (Remote)
        KMSAdapter->>Gateway: space/encryption/setup<br/>UCAN invocation
        Gateway->>KMS: Create or Get RSA public key<br/>for space DID
        KMS-->>Gateway: RSA public key (PEM)
        Gateway-->>KMSAdapter: {publicKey, keyReference, provider, algorithm}
        
        Note over KMSAdapter: Encrypt symmetric key<br/>with RSA-OAEP
        KMSAdapter->>KMSAdapter: encryptWithRSA(key+iv, publicKey)
    end

    rect rgb(248, 255, 248)
        Note over KMSAdapter,Storage: Metadata Creation & Upload
        KMSAdapter->>KMSAdapter: Create KMS metadata<br/>{encryptedSymmetricKey, space, kms}
        KMSAdapter->>Storage: Upload CAR file<br/>(encrypted file + metadata)
        Storage-->>KMSAdapter: Content CID
    end

    KMSAdapter-->>User: Upload successful (CID)

    Note over User,Storage: DECRYPTION FLOW

    User->>KMSAdapter: retrieveAndDecryptFile(cid, decryptionOptions)
    
    rect rgb(248, 255, 248)
        Note over KMSAdapter,Storage: Fetch Encrypted Data
        KMSAdapter->>Storage: Fetch CAR file by CID
        Storage-->>KMSAdapter: Encrypted CAR data
        KMSAdapter->>KMSAdapter: extractEncryptedMetadata(car)<br/>Parse KMS metadata
    end

    rect rgb(255, 248, 240)
        Note over KMSAdapter,KMS: Key Decryption (Remote)
        KMSAdapter->>Gateway: space/encryption/key/decrypt<br/>UCAN invocation + encryptedKey + proof
        Gateway->>KMS: Decrypt symmetric key<br/>with RSA private key
        KMS-->>Gateway: Decrypted symmetric key (base64)
        Gateway-->>KMSAdapter: {decryptedSymmetricKey}
        
        Note over KMSAdapter: Split combined key+iv
        KMSAdapter->>KMSAdapter: splitKeyAndIV(decryptedKey)
    end

    rect rgb(240, 248, 255)
        Note over KMSAdapter,SymCrypto: File Decryption (Local)
        KMSAdapter->>SymCrypto: decryptStream(encryptedData, key, iv)
        SymCrypto-->>KMSAdapter: Decrypted file stream
    end

    KMSAdapter-->>User: Decrypted file
    

Loading