Documentation de la Librairie JavaScript

La Librairie JavaScript Sharokey est une solution à fichier unique pour gérer les secrets chiffrés avec l'architecture Zero Knowledge. API identique aux commandes CLI.

Installation

html

<!-- Inclure depuis le CDN (dernière version) -->
<script src="https://cdn.jsdelivr.net/gh/Sharokey/sharokey-cdn@latest/sharokey.js"></script>

<!-- Ou version spécifique pour la production -->
<script src="https://cdn.jsdelivr.net/gh/Sharokey/[email protected]/sharokey.js"></script>

<script>
    // Configurer une fois
    Sharokey.config({token: 'votre_token_api_ici'});
    
    // Tester la connectivité
    const results = await Sharokey.test();
    console.log('Tests réussis :', results.passed + '/' + results.total);
</script>

Commandes

Méthode	Équivalent CLI	Description	Exemple
`config()`	`sharokey config`	Configurer le token	`Sharokey.config({token: 'TOKEN'})`
`create()`	`sharokey create`	Créer un secret	`Sharokey.create("motdepasse", 24, 1)`
`list()`	`sharokey list`	Lister les secrets	`Sharokey.list({limit: 10, status: 'active'})`
`get()`	`sharokey get`	Obtenir les détails d'un secret	`Sharokey.get('ABC123')`
`delete()`	`sharokey delete`	Expirer un secret (efface le contenu)	`Sharokey.delete('ABC123')`
`stats()`	`sharokey stats`	Afficher les statistiques	`Sharokey.stats()`
`test()`	`sharokey test`	Tester la connectivité	`Sharokey.test()`

Requêtes de Secrets

Méthode	Équivalent CLI	Description	Exemple
`createRequest()`	`sharokey create-request`	Créer une requête	`Sharokey.createRequest({message: "Partager identifiants", secretExpirationHours: 24, requestExpirationHours: 48, maximumViews: 1, locale: "fr"})`
`listRequests()`	`sharokey list-requests`	Lister les requêtes	`Sharokey.listRequests({status: 'active', limit: 10})`
`getRequest()`	`sharokey get-request`	Obtenir les détails d'une requête	`Sharokey.getRequest('abc123token456')`
`deleteRequest()`	`sharokey delete-request`	Expirer une requête (annule)	`Sharokey.deleteRequest('abc123token456')`
`requestStats()`	`sharokey request-stats`	Statistiques des requêtes	`Sharokey.requestStats()`

Paramètres

Créer un Secret

Paramètre	Description	Exemple
`content`	Contenu du secret (255 caractères max)	`"Mot de passe base de données : admin123"`
`hours`	Heures d'expiration (1-1000)	`24`
`views`	Vues maximum (1-10)	`1`
`options.description`	Description du secret (255 caractères max)	`{description: "Identifiants BD"}`
`options.message`	Message pour le visualiseur (255 caractères max)	`{message: "Utiliser avec précaution"}`
`options.password`	Protection additionnelle (4-100 caractères)	`{password: "secret123"}`
`options.captcha`	Activer la vérification CAPTCHA	`{captcha: true}`
`options.otpEmail`	OTP par email (format valide)	`{otpEmail: "[email protected]"}`
`options.otpPhone`	OTP par SMS (format international)	`{otpPhone: "+33674747474"}`
`options.ipWhitelist`	IPs autorisées (255 caractères max)	`{ipWhitelist: "203.0.113.5,198.51.100.10"}`
`options.geolocation`	Pays autorisés (255 caractères max)	`{geolocation: "FR,US,DE"}`
`options.attachments`	Tableau de fichiers (10 fichiers, 10MB max)	`{attachments: [file1, file2]}`

Priorité de Sécurité

Si plusieurs options de sécurité sont spécifiées, seul le niveau le plus élevé est appliqué :
captcha < password < otpEmail < otpPhone (le plus élevé)

Exemple : {password: "secret", captcha: true, otpPhone: "+33123456789"} → Seul l'OTP téléphone sera utilisé

Configuration

Paramètre	Description	Exemple
`token`	Token API (requis)	`{token: 'abcd1234...'}`
`timeout`	Timeout de requête en millisecondes	`{timeout: 60000}`

Format de Sortie

Toutes les méthodes retournent des objets JSON (même structure que la sortie JSON CLI).

Exemples

Utilisation de Base

javascript

// Secret simple
const secret = await Sharokey.create("Mot de passe base de données : admin123", 24, 1);
console.log('URL de partage :', secret.share_url);


// Avec description et message
const secret2 = await Sharokey.create(
    "Identifiants API", 
    48, //Heures d'expiration
    3, //Vues maximum
    {
        description: "Accès API de production",
        message: "Valable jusqu'à la fin du projet"
    }
);


// Protection CAPTCHA
const secret3 = await Sharokey.create(
    "Accès serveur", 
    12, //Heures d'expiration
    1, //Vues maximum
    {
        captcha: true
    }
);


// Protection par mot de passe  
const secret4 = await Sharokey.create(
    "Données sensibles", 
    6, //Heures d'expiration
    2, //Vues maximum
    {
        password: "monMotDePasseSecret123"
    }
);


// Protection OTP email (priorité plus élevée que le mot de passe)
const secret5 = await Sharokey.create(
    "Détails bancaires", 
    24, //Heures d'expiration
    1, //Vues maximum
    {
        password: "sauvegarde",
        otpEmail: "[email protected]"
    }
);


// Protection OTP SMS (priorité la plus élevée - remplacera tous les autres)
const secret6 = await Sharokey.create(
    "Accès critique", 
    2, //Heures d'expiration
    1, //Vues maximum
    {
        password: "sauvegarde",
        captcha: true,
        otpEmail: "[email protected]",
        otpPhone: "+33674747474"
    }
);


// Restriction IP
const secret7 = await Sharokey.create(
    "Accès externe", 
    48, //Heures d'expiration
    10, //Vues maximum
    {
        ipWhitelist: "203.0.113.5,198.51.100.10"
    }
);


// Restriction géolocalisation
const secret8 = await Sharokey.create(
    "Données UE uniquement", 
    72, //Heures d'expiration
    5, //Vues maximum
    {
        geolocation: "FR,DE,BE,IT,ES"
    }
);


// Restrictions combinées
const secret9 = await Sharokey.create(
    "Accès restreint", 
    24, //Heures d'expiration
    2, //Vues maximum
    {
        password: "secure123",
        ipWhitelist: "203.0.113.100",
        geolocation: "FR,US"
    }
);

Pièces Jointes de Fichiers

html

<input type="file" id="fileInput" multiple>
<button onclick="shareWithFiles()">Partager Secret</button>


<script>
async function shareWithFiles() {
    const files = Array.from(document.getElementById('fileInput').files);
    
    const secret = await Sharokey.create("Fichiers contrat", 48, 5, {
        description: "Documents client XYZ",
        attachments: files
    });
    
    console.log('URL de partage avec pièces jointes :', secret.share_url);
}
</script>

Requêtes de Secrets

javascript

// Créer une requête avec livraison par email (sortie JSON par défaut - réponse API directe)
const request = await Sharokey.createRequest({
    message: "Veuillez partager les identifiants VPN",
    emailTo: "[email protected]",
    emailReply: "[email protected]",
    requestExpirationHours: 48,
    secretExpirationHours: 24,
    maximumViews: 3,
    locale: "fr"
});
console.log('URL de requête :', request.url);


// Obtenir les détails d'une requête par token (JSON par défaut - réponse API directe)
const requestDetails = await Sharokey.getRequest('abc123token456');


// Lister les requêtes avec filtres (JSON par défaut - réponse API directe)
const requests = await Sharokey.listRequests({
    status: 'active',
    limit: 20
});


// Expirer une requête par token (annule et la rend inactive)
await Sharokey.deleteRequest('abc123token456');


// Voir les statistiques des requêtes (JSON uniquement - réponse API directe)
const stats = await Sharokey.requestStats();


// Paramètres de requête : secretExpirationHours (1-1000), requestExpirationHours (1-1000), maximumViews (1-10)
// Champs email : emailTo et emailReply (format email valide requis)
// Locale : "fr" ou "en" - définit la langue de l'email lors de l'envoi de notifications

Gestion

javascript

// Lister tous les secrets
const allSecrets = await Sharokey.list();


// Lister avec filtres
const filtered = await Sharokey.list({
    status: 'active',
    creator: '[email protected]',
    limit: 20
});


// Sortie JSON (par défaut)
const secrets = await Sharokey.list({limit: 5});
// Sortie : {"success": true, "count": 2, "secrets": [{"slug": "ABC123", "maximum_views": 1, ...}]}


// Obtenir les détails d'un secret
const secret = await Sharokey.get('ABC123');


// Expirer un secret (efface le contenu, force l'expiration)
await Sharokey.delete('ABC123');


// Statistiques
const stats = await Sharokey.stats();

Limites & Contraintes

Contenu & Texte

Contenu du secret : 255 caractères max (avant chiffrement)
Description : 255 caractères max
Message : 255 caractères max
Mot de passe : 4-100 caractères
Liste blanche IP : 255 caractères max (IPs publiques uniquement, séparées par des virgules)
Géolocalisation : 255 caractères max (codes pays ISO)

Pièces Jointes

Fichiers maximum : 10 par secret
Taille totale : 10MB pour tous les fichiers
Formats supportés : Documents, Images, Audio, Vidéo, Archives
Chiffrement : Fichiers chiffrés côté client avant téléchargement

Temps & Accès

Expiration : 1-1000 heures
Vues maximum : 1-10 vues

Sécurité

Architecture Zero Knowledge

Chiffrement côté client : AES-GCM-256 avec PBKDF2 (10 000 itérations)
Clés divisées : CléA (envoyée au serveur) + CléB (dans le fragment d'URL)
Pas d'accès serveur : Le serveur ne peut pas déchiffrer les secrets
Perfect Forward Secrecy : Les clés ne sont jamais stockées côté serveur

Meilleures Pratiques

Utiliser des temps d'expiration courts pour les données sensibles
Limiter le nombre de vues de manière appropriée
Choisir le niveau de sécurité approprié : OTP téléphone (le plus élevé) > OTP email > mot de passe > CAPTCHA
Combiner avec des restrictions IP et géographiques pour le contrôle d'accès
Seul le niveau de sécurité le plus élevé sera appliqué si plusieurs sont spécifiés

Exigences Navigateur

Chrome : 60+
Firefox : 55+
Safari : 11+
Edge : 79+
Web Crypto API : Requis pour le chiffrement

Utilitaires

Test de Connectivité

javascript

// Test simple (booléen)
const isConnected = await Sharokey.testConnection();


// Test détaillé (comme CLI)
const results = await Sharokey.test();
console.log(`Tests : ${results.passed}/${results.total}`);
// Sortie : {config: true, network: true, auth: true, read: true, stats: true, total: 5, passed: 5, success: true}

Détails du Test :

Config - Valide la configuration du token API
Network - Test de connectivité HTTP (appelle l'endpoint /health)
Auth - Vérification de l'authentification via API
Read - Test de permission de listage des secrets
Stats - Test d'accès à l'endpoint de statistiques

Détails de la Fonction Test

La fonction test() effectue des diagnostics complets côté client incluant la vérification de la santé du serveur, la validation de l'authentification, et les vérifications de permissions. Cela garantit une fonctionnalité API complète au-delà de la connectivité de base.

Gestion d'Erreurs

javascript

try {
    const secret = await Sharokey.create('Mon secret', 24, 1);
    console.log('Succès :', secret.share_url);
} catch (error) {
    console.error('Erreur :', error.message);
    
    // Erreurs courantes :
    // - "Token not configured" - Utiliser Sharokey.config() d'abord
    // - "Content is required" - Vérifier les paramètres
    // - "Hours must be between 1 and 1000" - Expiration invalide
    // - "Invalid phone format" - Utiliser le format +33674747474
    // - "Too many attachments" - Max 10 fichiers, 10MB total
}

Vérification de Compatibilité Navigateur

javascript

// Vérifier avant l'initialisation
if (!window.crypto || !window.crypto.subtle) {
    alert('Navigateur non supporté. Veuillez utiliser Chrome 60+, Firefox 55+, Safari 11+, ou Edge 79+');
} else {
    Sharokey.config({token: 'votre-token'});
}

Intégration Rapide

Exemple Complet

html

<!DOCTYPE html>
<html>
<head>
    <title>Intégration Sharokey</title>
    <script src="https://cdn.jsdelivr.net/gh/Sharokey/sharokey-cdn@latest/sharokey.js"></script>
</head>
<body>
    <form id="secretForm">
        <textarea id="content" placeholder="Contenu du secret" required></textarea>
        <input type="number" id="hours" value="24" min="1" max="1000" placeholder="Heures">
        <input type="number" id="views" value="1" min="1" max="10" placeholder="Vues">
        <input type="password" id="password" placeholder="Mot de passe (optionnel)">
        <input type="file" id="files" multiple>
        <button type="submit">Créer Secret</button>
    </form>
    
    <div id="result"></div>


    <script>
        // Configurer
        Sharokey.config({token: 'votre_token_api_ici'});


        // Gérer le formulaire
        document.getElementById('secretForm').onsubmit = async (e) => {
            e.preventDefault();
            
            try {
                const options = {};
                const password = document.getElementById('password').value;
                const files = Array.from(document.getElementById('files').files);
                
                if (password) options.password = password;
                if (files.length) options.attachments = files;
                
                const secret = await Sharokey.create(
                    document.getElementById('content').value,
                    parseInt(document.getElementById('hours').value),
                    parseInt(document.getElementById('views').value),
                    options
                );
                
                document.getElementById('result').innerHTML = 
                    `<p>Secret créé ! <br><a href="${secret.share_url}" target="_blank">${secret.share_url}</a></p>`;
                    
                document.getElementById('secretForm').reset();
                
            } catch (error) {
                document.getElementById('result').innerHTML = 
                    `<p style="color:red">Erreur : ${error.message}</p>`;
            }
        };
    </script>
</body>
</html>

Ressources Connexes

SDK Python - Librairie Python côté serveur
Documentation CLI - Référence de l'interface en ligne de commande
Structures de Réponse - Documentation complète des réponses JSON
Comparaison de Fonctionnalités - Comparer toutes les librairies Sharokey

Dépannage

Problèmes courants :

"Token not configured" : Utiliser Sharokey.config({token: 'TOKEN'}) d'abord
"Web Crypto API not supported" : Mettre à jour le navigateur (Chrome 60+, Firefox 55+, Safari 11+, Edge 79+)
"Content is required" : Vérifier le paramètre de contenu du secret
"Invalid phone format" : Utiliser le format international (+33674747474)
"Too many attachments" : Max 10 fichiers, 10MB total
"IP whitelist error" : Seules les adresses IP publiques sont supportées

Documentation de la Librairie JavaScript ​

Installation ​

Commandes ​

Requêtes de Secrets ​

Paramètres ​

Créer un Secret ​

Configuration ​

Format de Sortie ​

Exemples ​

Utilisation de Base ​

Pièces Jointes de Fichiers ​

Requêtes de Secrets ​

Gestion ​

Limites & Contraintes ​

Contenu & Texte ​

Pièces Jointes ​

Temps & Accès ​

Sécurité ​

Architecture Zero Knowledge ​

Meilleures Pratiques ​

Exigences Navigateur ​

Utilitaires ​

Test de Connectivité ​

Gestion d'Erreurs ​

Vérification de Compatibilité Navigateur ​

Intégration Rapide ​

Exemple Complet ​

Ressources Connexes ​

Dépannage ​

Documentation de la Librairie JavaScript

Installation

Commandes

Requêtes de Secrets

Paramètres

Créer un Secret

Configuration

Format de Sortie

Exemples

Utilisation de Base

Pièces Jointes de Fichiers

Requêtes de Secrets

Gestion

Limites & Contraintes

Contenu & Texte

Pièces Jointes

Temps & Accès

Sécurité

Architecture Zero Knowledge

Meilleures Pratiques

Exigences Navigateur

Utilitaires

Test de Connectivité

Gestion d'Erreurs

Vérification de Compatibilité Navigateur

Intégration Rapide

Exemple Complet

Ressources Connexes

Dépannage