Nostr WoT

API de l’extension

L’extension expose window.nostr pour l’identité, la signature d’événements et le chiffrement des messages NIP-04/NIP-44.

Installez l’extension, sélectionnez un compte et connectez votre site à l’invite. La signature et le chiffrement nécessitent un compte capable de signer et peuvent demander le déverrouillage du coffre. Lire une clé publique connue ne nécessite pas de le déverrouiller.

Configuration

Vérifiez la présence de la méthode voulue avant de l’appeler. La présence du fournisseur ne signifie pas que le site est connecté ou qu’une requête est autorisée.

javascript
// Feature detection
function hasNostr() {
  return typeof window !== "undefined" &&
         typeof window.nostr?.getPublicKey === "function";
}

// Wait for the extension to load
async function waitForNostr(timeout = 3000) {
  const start = Date.now();
  while (!hasNostr() && Date.now() - start < timeout) {
    await new Promise(r => setTimeout(r, 100));
  }
  return hasNostr();
}

API de signature NIP-07

L’extension implémente l’API de signature NIP-07 via window.nostr.

getPublicKey()

Renvoie la clé publique hexadécimale du compte actif. Nécessite la connexion du site et l’accès à l’identité.

Retour

Promise<string>

Exemple

javascript
const pubkey = await window.nostr.getPublicKey();
console.log(pubkey); // "3bf0c63f..."

signEvent(event)

Signe l’événement et ajoute id, pubkey et sig. Fournissez created_at ; le signataire conserve cet horodatage. Si vous fournissez pubkey, elle doit correspondre au compte actif. Signer ne publie pas l’événement.

Paramètres

NomTypeDescription
eventUnsignedEventÉvénement contenant kind, content, tags et created_at (temps Unix en secondes)

Retour

Promise<SignedEvent>

Exemple

javascript
const signed = await window.nostr.signEvent({
  kind: 1,
  content: "Hello Nostr!",
  tags: [],
  created_at: Math.floor(Date.now() / 1000),
});
console.log(signed.sig); // schnorr signature

nip04.encrypt(pubkey, plaintext)

Chiffre un message avec NIP-04, l’ancien format de chiffrement des messages directs.

Paramètres

NomTypeDescription
pubkeystringClé publique du destinataire, composée de 64 caractères hexadécimaux
plaintextstringMessage à chiffrer

Retour

Promise<string>

Exemple

javascript
const encrypted = await window.nostr.nip04.encrypt(
  recipientPubkey,
  "Secret message"
);

nip04.decrypt(pubkey, ciphertext)

Déchiffre un message NIP-04.

Paramètres

NomTypeDescription
pubkeystringClé publique de l’expéditeur, composée de 64 caractères hexadécimaux
ciphertextstringChaîne du message chiffré

Retour

Promise<string>

Exemple

javascript
const plaintext = await window.nostr.nip04.decrypt(
  senderPubkey,
  ciphertext
);
console.log(plaintext); // "Secret message"

nip44.encrypt(pubkey, plaintext)

Chiffre un message avec NIP-44. Cet exemple utilise l’appel standard à deux arguments.

Paramètres

NomTypeDescription
pubkeystringClé publique du destinataire, composée de 64 caractères hexadécimaux
plaintextstringMessage à chiffrer

Retour

Promise<string>

Exemple

javascript
const encrypted = await window.nostr.nip44.encrypt(
  recipientPubkey,
  "Secret message"
);

nip44.decrypt(pubkey, ciphertext)

Déchiffre un message NIP-44.

Paramètres

NomTypeDescription
pubkeystringClé publique de l’expéditeur, composée de 64 caractères hexadécimaux
ciphertextstringChaîne du message chiffré

Retour

Promise<string>

Exemple

javascript
const plaintext = await window.nostr.nip44.decrypt(
  senderPubkey,
  ciphertext
);
console.log(plaintext); // "Secret message"

getRelays()

Renvoie les URL des relais configurés dans l’extension. Chaque entrée contient read: true et write: true. Cette méthode ne récupère pas les politiques de relais NIP-65 du compte et peut renvoyer un objet vide.

Retour

Promise<Record<string, { read: boolean; write: boolean }>>

Exemple

javascript
const relays = await window.nostr.getRelays();

// {
//   "wss://relay.damus.io": { read: true, write: true },
//   "wss://nos.lol": { read: true, write: true }
// }

Connexion, permissions et erreurs

Les appels renvoient des promesses et peuvent échouer si l’utilisateur refuse, si le site est déconnecté, si l’accès à l’identité est désactivé ou si le délai expire. Les comptes en lecture seule ne peuvent ni signer ni chiffrer.

Un changement de compte peut invalider une requête en attente. Les appels depuis la page expirent après 120 secondes, attente de connexion, de permission ou de déverrouillage comprise. Interceptez les erreurs et permettez de réessayer ; les messages d’erreur ne sont pas des codes stables destinés au traitement automatique.

javascript
async function signNote(content) {
  const provider = window.nostr;
  if (typeof provider?.getPublicKey !== "function" ||
      typeof provider?.signEvent !== "function") {
    return { ok: false, reason: "provider-unavailable" };
  }

  try {
    const pubkey = await provider.getPublicKey();
    if (!pubkey) return { ok: false, reason: "no-active-account" };

    const event = await provider.signEvent({
      pubkey,
      kind: 1,
      content,
      tags: [],
      created_at: Math.floor(Date.now() / 1000),
    });
    return { ok: true, event };
  } catch (error) {
    return { ok: false, reason: "request-failed", error };
  }
}

Utilisez le SDK pour interroger le graphe des abonnements et l’API WoT Oracle pour consulter les mises en sourdine publiques. Ces informations sont distinctes de la distance dans le graphe et ne produisent pas de score de confiance combiné. L’extension fournit l’identité et la signature.

Utiliser le portefeuille avec WebLN

Appelez enable() avant les opérations. sendPayment() reçoit une facture BOLT11 et renvoie une préimage après paiement. L’extension expose aussi getInfo(), makeInvoice() et getBalance() ; vérifiez ces capacités optionnelles.

Exemple

javascript
// Call from a Pay button after the user reviews the invoice.
export async function payInvoice(paymentRequest) {
  const provider = window.webln;
  if (!provider?.enable || !provider?.sendPayment) {
    throw new Error("A WebLN wallet is required");
  }
  await provider.enable();
  return provider.sendPayment(paymentRequest);
}

Notes d’intégration

Une connexion Nostr n’autorise pas le portefeuille. L’utilisateur doit le configurer et peut devoir approuver le paiement. Évitez les envois en double et affichez leur état. Après un délai dépassé, vérifiez le résultat dans le portefeuille avant de réessayer.

Ce que les sites peuvent utiliser

window.nostr expose identité NIP-07, signatures et méthodes de chiffrement disponibles ; window.webln expose les opérations du portefeuille. Détectez les méthodes optionnelles. Les comptes par passkey, phrase ou signataire distant partagent cette interface.

Notes d’intégration

Le coffre, les fichiers de récupération, les archives et les RPC internes ne sont pas des API web publiques. Ne demandez jamais la phrase secrète. Un compte en lecture seule ne signe pas ; un signataire distant peut demander une approbation externe. Utilisez les outils graphe et Oracle du SDK pour la confiance.

Référence et options supplémentaires

Signer, publier et afficher les résultats

La signature et la publication sont distinctes. Obtenez un événement signé par NIP-07, puis envoyez-le aux relais choisis. L’exemple indique l’acceptation par relais et ferme son pool temporaire.

terminal
$npm install nostr-tools

Exemple

typescript
import { SimplePool, verifyEvent, type Event } from "nostr-tools";

// Pass the event returned by window.nostr.signEvent().
export async function publishNote(event: Event, relays: string[]) {
  if (!verifyEvent(event)) throw new Error("Invalid signed event");
  if (relays.length === 0) throw new Error("Choose at least one relay");
  const pool = new SimplePool();
  try {
    const results = await Promise.allSettled(pool.publish(relays, event));
    return results.map((result, i) => ({
      relay: relays[i], accepted: result.status === "fulfilled",
    }));
  } finally {
    pool.close(relays);
  }
}

Notes d’intégration

La signature prouve l’auteur, pas la livraison. N’indiquez un succès que pour les relais ayant accepté l’événement. Conservez les succès partiels et réutilisez le même événement signé lors des reprises. Dans une application durable, réutilisez le transport existant.

Permissions et changements de compte

Demandez la clé publique depuis Connexion et les signatures depuis l’action correspondante. L’extension peut demander connexion, déverrouillage ou approbation. Une permission passée ne couvre pas automatiquement un autre compte.

Exemple

javascript
// Mount once in your app and call the returned cleanup on unmount.
export function watchAccount(onAccountChanged) {
  const reset = () => onAccountChanged();
  window.addEventListener("nostr:accountChanged", reset);
  return () => window.removeEventListener("nostr:accountChanged", reset);
}

// In onAccountChanged: clear account-specific views and pending drafts,
// stop subscriptions and require a fresh connection before signing.
// Other NIP-07 extensions may not emit this Nostr WoT-specific event.

Notes d’intégration

Le signal de changement de compte est spécifique à Nostr WoT. Revérifiez l’identité avant une action sensible et ignorez les réponses obsolètes. Conservez le brouillon et proposez une reprise après un refus, sans boucle automatique de demandes. HTTP utilise le type 27235 ; AUTH de relais utilise 22242.