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.
// 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
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
| Nome | Tipo | Descrizione |
|---|---|---|
event | UnsignedEvent | Evento contenente kind, content, tags e created_at (tempo Unix in secondi) |
Restituisce
Promise<SignedEvent>
Esempio
const signed = await window.nostr.signEvent({
kind: 1,
content: "Hello Nostr!",
tags: [],
created_at: Math.floor(Date.now() / 1000),
});
console.log(signed.sig); // schnorr signaturenip04.encrypt(pubkey, plaintext)
Cifra un messaggio con NIP-04, il precedente formato di crittografia dei messaggi diretti.
Parametri
| Nome | Tipo | Descrizione |
|---|---|---|
pubkey | string | Chiave pubblica del destinatario con 64 caratteri esadecimali |
plaintext | string | Messaggio da cifrare |
Restituisce
Promise<string>
Esempio
const encrypted = await window.nostr.nip04.encrypt(
recipientPubkey,
"Secret message"
);nip04.decrypt(pubkey, ciphertext)
Decifra un messaggio NIP-04.
Parametri
| Nome | Tipo | Descrizione |
|---|---|---|
pubkey | string | Chiave pubblica del mittente con 64 caratteri esadecimali |
ciphertext | string | Stringa del messaggio cifrato |
Restituisce
Promise<string>
Esempio
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
| Nome | Tipo | Descrizione |
|---|---|---|
pubkey | string | Chiave pubblica del destinatario con 64 caratteri esadecimali |
plaintext | string | Messaggio da cifrare |
Restituisce
Promise<string>
Esempio
const encrypted = await window.nostr.nip44.encrypt(
recipientPubkey,
"Secret message"
);nip44.decrypt(pubkey, ciphertext)
Decifra un messaggio NIP-44.
Parametri
| Nome | Tipo | Descrizione |
|---|---|---|
pubkey | string | Chiave pubblica del mittente con 64 caratteri esadecimali |
ciphertext | string | Stringa del messaggio cifrato |
Restituisce
Promise<string>
Esempio
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
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.
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
// 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.
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.
Esempio
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
// 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.