Nostr WoT

API dell’estensione

L’estensione espone window.nostr per identità, firma degli eventi e crittografia dei messaggi NIP-04/NIP-44.

Installa l’estensione, seleziona un account e collega il sito quando richiesto. Firma e crittografia richiedono un account in grado di firmare e possono richiedere lo sblocco del vault. Leggere una chiave pubblica nota non richiede lo sblocco.

Configurazione

Verifica che il metodo necessario esista prima di chiamarlo. La presenza del provider non significa che il sito sia collegato o che una richiesta sia autorizzata.

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 di firma NIP-07

L’estensione implementa l’API di firma NIP-07 tramite window.nostr.

getPublicKey()

Restituisce la chiave pubblica esadecimale dell’account attivo. Richiede il collegamento del sito e l’accesso all’identità.

Restituisce

Promise<string>

Esempio

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

signEvent(event)

Firma l’evento e aggiunge id, pubkey e sig. Fornisci created_at; il firmatario conserva quel timestamp. Se fornisci pubkey, deve corrispondere all’account attivo. La firma non pubblica l’evento.

Parametri

NomeTipoDescrizione
eventUnsignedEventEvento contenente kind, content, tags e created_at (tempo Unix in secondi)

Restituisce

Promise<SignedEvent>

Esempio

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)

Cifra un messaggio con NIP-04, il precedente formato di crittografia dei messaggi diretti.

Parametri

NomeTipoDescrizione
pubkeystringChiave pubblica del destinatario con 64 caratteri esadecimali
plaintextstringMessaggio da cifrare

Restituisce

Promise<string>

Esempio

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

nip04.decrypt(pubkey, ciphertext)

Decifra un messaggio NIP-04.

Parametri

NomeTipoDescrizione
pubkeystringChiave pubblica del mittente con 64 caratteri esadecimali
ciphertextstringStringa del messaggio cifrato

Restituisce

Promise<string>

Esempio

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

nip44.encrypt(pubkey, plaintext)

Cifra un messaggio con NIP-44. Questo esempio usa la chiamata standard con due argomenti.

Parametri

NomeTipoDescrizione
pubkeystringChiave pubblica del destinatario con 64 caratteri esadecimali
plaintextstringMessaggio da cifrare

Restituisce

Promise<string>

Esempio

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

nip44.decrypt(pubkey, ciphertext)

Decifra un messaggio NIP-44.

Parametri

NomeTipoDescrizione
pubkeystringChiave pubblica del mittente con 64 caratteri esadecimali
ciphertextstringStringa del messaggio cifrato

Restituisce

Promise<string>

Esempio

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

getRelays()

Restituisce gli URL dei relay configurati nell’estensione. Ogni voce contiene read: true e write: true. Questo metodo non recupera le politiche dei relay NIP-65 dell’account e può restituire un oggetto vuoto.

Restituisce

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

Esempio

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

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

Collegamento, autorizzazioni ed errori

Le chiamate restituiscono promesse e possono fallire se l’utente rifiuta, il sito è scollegato, l’accesso all’identità è disabilitato o scade il tempo. Gli account di sola lettura non possono firmare né cifrare.

Un cambio di account può invalidare una richiesta in attesa. Le chiamate dalla pagina scadono dopo 120 secondi, inclusa l’attesa di collegamento, autorizzazione o sblocco. Gestisci gli errori e consenti di riprovare; i messaggi di errore non sono codici stabili per l’elaborazione automatica.

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 };
  }
}

Usa l’SDK per interrogare il grafo dei follow e l’API WoT Oracle per consultare i silenziamenti pubblici. Queste informazioni sono separate dalla distanza nel grafo e non producono un punteggio di fiducia combinato. L’estensione fornisce identità e firma.

Usare la wallet dell’estensione con WebLN

Chiama enable() prima delle operazioni. sendPayment() accetta una fattura BOLT11 e restituisce una preimmagine dopo il pagamento. Sono disponibili anche getInfo(), makeInvoice() e getBalance(); verifica le capacità opzionali.

Esempio

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);
}

Note di integrazione

Una connessione Nostr non autorizza la wallet. L’utente deve configurarla e potrebbe dover approvare il pagamento. Evita invii duplicati e mostra lo stato. Dopo un timeout controlla il risultato nella wallet prima di riprovare.

Cosa possono usare i siti

window.nostr espone identità NIP-07, firme e cifratura supportata; window.webln espone la wallet. Rileva i metodi opzionali prima dell’uso. Account passkey, seed e remoti condividono l’interfaccia per i siti.

Note di integrazione

Vault, file di recupero, archivio e RPC interni non sono API pubbliche per i siti. L’app non richiede il seed. Gli account di sola lettura non firmano; un firmatario remoto può richiedere approvazione esterna. Usa grafo SDK e Oracle per interrogazioni sulla fiducia.

Riferimento e altre opzioni

Firmare, pubblicare e mostrare i risultati

Firma e pubblicazione sono operazioni separate. Ottieni l’evento firmato via NIP-07 e invialo ai relay scelti. L’esempio restituisce l’accettazione per relay e chiude il pool temporaneo.

terminale
$npm install nostr-tools

Esempio

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);
  }
}

Note di integrazione

La firma prova l’autore, non la consegna. Mostra successo solo per i relay che hanno accettato. Conserva i successi parziali e riusa evento firmato e ID nei tentativi successivi. Nelle app persistenti riutilizza il trasporto relay esistente.

Permessi e cambio account

Richiedi la chiave pubblica da Connetti e le firme dall’azione corrispondente. L’estensione può chiedere connessione, sblocco o approvazione. Un permesso passato non copre automaticamente altri account o operazioni.

Esempio

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.

Note di integrazione

L’evento di cambio account è specifico di Nostr WoT. Ricontrolla l’identità prima di azioni sensibili e scarta risposte obsolete. Cattura i rifiuti, conserva la bozza e offri un nuovo tentativo. Non ripetere automaticamente richieste annullate. HTTP usa il tipo 27235, AUTH relay il 22242.