🚀 Release Candidate: Zero-Knowledge Public Sharing

What's New

lumen-cool/sdk introduces a major cryptographic architecture upgrade. This release transitions from deterministic root-key encryption to a fully decoupled, asymmetric-style sharing model designed for stronger isolation and flexibility.

✨ Feature Highlight: Public Shareable Links

You can now generate zero-knowledge public download links for your files.

• Each uploaded file is encrypted with a unique, randomly generated 256-bit key.
• The file key is securely wrapped with your Master Key for authenticated access.
• Sharing files: Export the raw file key into a URL fragment (#...). Because fragments are never transmitted to the server, only someone with the full link can decrypt the file.

Code Example

$mnemonic = 'your bip39 mnemonic phrase ...';

$file = $client->upload(__DIR__ . '/photo.jpg', '01jh2tcnx48caj4wsdkjevtr2h', [
    'mime_type' => 'image/jpeg',
    'encryption' => [
        'mnemonic' => $mnemonic
    ]
]);

// Optionally interact with the keys (for sharing)
use Lumen\Sdk\LumenKeyManager;

$masterKey = LumenKeyManager::deriveMasterKeyFromMnemonic($mnemonic);
$fileKey = LumenKeyManager::unwrapFileKey(
    base64_decode(
        string: $file->toArray()['encryption']['wrapped_key'],
        strict: true
    ),
    $masterKey
);

$shareableLink = $client->generateShareableLink(
    'https://app.lumen.cool',
    $file->getFederatedId(),
    $fileKey
);

echo "Share this link: " . $shareableLink;
// Example output:
// https://app.lumen.cool/files/123-abc/view#Base64UrlKey...

🔒 Security & API Breaking Changes (v2 Cutover)

• Hard Cutover (Protocol v2): The SDK now enforces the v2 cryptographic standard internally via the x-lumen-ce-v header. Version negotiation and header management are handled automatically, and legacy (v1) payloads are not supported.
• Backward Compatibility: Files created with the Lumen CE v1 cannot be decrypted by Lumen CE v2 clients.
• APM & Memory Safety: Sensitive key material is protected using PHP 8.2 #[\SensitiveParameter] attributes and sodium_memzero lifecycle hooks, reducing the risk of exposure in logs, traces, or memory.

Notes

This release candidate reflects the finalized direction for 1.0.0. Final validation, compatibility checks, and production readiness reviews are recommended before tagging the stable release.