API de la extensión
La extensión expone window.nostr para identidad, firma de eventos y cifrado de mensajes NIP-04/NIP-44.
Instala la extensión, selecciona una cuenta y conecta tu sitio cuando se solicite. La firma y el cifrado requieren una cuenta capaz de firmar y pueden pedir que desbloquees la bóveda. Leer una clave pública conocida no requiere desbloquearla.
Configuración
Comprueba que el método que necesitas existe antes de llamarlo. La presencia del proveedor no significa que el sitio esté conectado ni que una solicitud esté aprobada.
// 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 firma NIP-07
La extensión implementa la API de firma NIP-07 mediante window.nostr.
getPublicKey()
Devuelve la clave pública hexadecimal de la cuenta activa. Requiere conectar el sitio y permitir el acceso a la identidad.
Devuelve
Promise<string>
Ejemplo
const pubkey = await window.nostr.getPublicKey();
console.log(pubkey); // "3bf0c63f..."signEvent(event)
Firma el evento y añade id, pubkey y sig. Debes proporcionar created_at; el firmante conserva esa fecha. Si incluyes pubkey, debe coincidir con la cuenta activa. Firmar no publica el evento.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
event | UnsignedEvent | Evento con kind, content, tags y created_at (tiempo Unix en segundos) |
Devuelve
Promise<SignedEvent>
Ejemplo
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 mensaje mediante NIP-04, el formato antiguo de cifrado de mensajes directos.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
pubkey | string | Clave pública del destinatario, con 64 caracteres hexadecimales |
plaintext | string | Mensaje que se cifrará |
Devuelve
Promise<string>
Ejemplo
const encrypted = await window.nostr.nip04.encrypt(
recipientPubkey,
"Secret message"
);nip04.decrypt(pubkey, ciphertext)
Descifra un mensaje NIP-04.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
pubkey | string | Clave pública del remitente, con 64 caracteres hexadecimales |
ciphertext | string | Cadena del mensaje cifrado |
Devuelve
Promise<string>
Ejemplo
const plaintext = await window.nostr.nip04.decrypt(
senderPubkey,
ciphertext
);
console.log(plaintext); // "Secret message"nip44.encrypt(pubkey, plaintext)
Cifra un mensaje mediante NIP-44. Este ejemplo usa la llamada estándar de dos argumentos.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
pubkey | string | Clave pública del destinatario, con 64 caracteres hexadecimales |
plaintext | string | Mensaje que se cifrará |
Devuelve
Promise<string>
Ejemplo
const encrypted = await window.nostr.nip44.encrypt(
recipientPubkey,
"Secret message"
);nip44.decrypt(pubkey, ciphertext)
Descifra un mensaje NIP-44.
Parámetros
| Nombre | Tipo | Descripción |
|---|---|---|
pubkey | string | Clave pública del remitente, con 64 caracteres hexadecimales |
ciphertext | string | Cadena del mensaje cifrado |
Devuelve
Promise<string>
Ejemplo
const plaintext = await window.nostr.nip44.decrypt(
senderPubkey,
ciphertext
);
console.log(plaintext); // "Secret message"getRelays()
Devuelve las URL de los relés configurados en la extensión. Cada entrada tiene read: true y write: true. Este método no consulta las políticas de relés NIP-65 de la cuenta y puede devolver un objeto vacío.
Devuelve
Promise<Record<string, { read: boolean; write: boolean }>>
Ejemplo
const relays = await window.nostr.getRelays();
// {
// "wss://relay.damus.io": { read: true, write: true },
// "wss://nos.lol": { read: true, write: true }
// }Conexión, permisos y errores
Las llamadas devuelven promesas y pueden rechazarse si el usuario no las autoriza, el sitio está desconectado, el acceso a la identidad está desactivado o se agota el tiempo. Las cuentas de solo lectura no pueden firmar ni cifrar.
Cambiar de cuenta puede invalidar una solicitud pendiente. Las llamadas desde la página caducan tras 120 segundos, incluida la espera de conexión, permiso o desbloqueo. Captura los errores y permite reintentar; los mensajes de error no son códigos estables para procesamiento automático.
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 el SDK para consultar el grafo de seguimientos y la API de WoT Oracle para obtener información sobre silenciamientos públicos. Esta información se presenta por separado de la distancia de seguimiento y no genera una puntuación de confianza combinada. La extensión proporciona identidad y firma.
Usar la wallet de la extensión con WebLN
Llama a enable() antes de las operaciones. sendPayment() recibe una factura BOLT11 y devuelve una preimagen al completarse el pago. La extensión también expone getInfo(), makeInvoice() y getBalance(); detecta estas capacidades opcionales.
Ejemplo
// 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);
}Notas de integración
Una conexión Nostr no autoriza la wallet. El usuario necesita configurarla y puede tener que conectarla o aprobar el pago. Evita envíos duplicados y muestra el estado. No repitas automáticamente tras un timeout: comprueba primero el resultado en la wallet.
Qué pueden usar los sitios web
La extensión expone window.nostr para identidad NIP-07, firmas y cifrado compatible, y window.webln para la wallet. Detecta cada método opcional antes de usarlo. Las cuentas con passkey, semilla o firmante remoto comparten la interfaz de firma para sitios web.
Notas de integración
La bóveda, los archivos de recuperación, el archivo de eventos y los RPC internos no son API públicas para sitios web. Tu aplicación no necesita la semilla. Las cuentas de solo lectura no firman. Un firmante remoto puede requerir aprobación externa. Usa las herramientas de grafo y Oracle del SDK para consultas de confianza.
Firmar, publicar y mostrar resultados
Firmar y publicar son operaciones independientes. Obtén el evento firmado mediante NIP-07 y envíalo a los relays elegidos por la aplicación y el usuario. El ejemplo devuelve la aceptación por relay y cierra su pool temporal.
Ejemplo
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);
}
}Notas de integración
Una firma acredita autoría, no entrega. Indica éxito solo en los relays que aceptaron el evento y conserva los resultados parciales. Para reintentar, reutiliza el mismo evento firmado y su ID. En aplicaciones persistentes, reutiliza el transporte existente en lugar de crear un pool por nota.
Permisos, cambios de cuenta y cancelación
Solicita la clave pública desde Conectar y firmas cuando el usuario realice la acción correspondiente. La extensión puede pedir conexión, desbloqueo o aprobación. No supongas que un permiso anterior cubre otra cuenta u operación.
Ejemplo
// 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.Notas de integración
El evento de cambio de cuenta es específico de Nostr WoT. Comprueba la identidad antes de completar acciones sensibles y descarta respuestas antiguas. Captura rechazos, conserva el borrador y ofrece reintentar. No repitas automáticamente las solicitudes canceladas. HTTP usa el tipo 27235; AUTH de relay usa el 22242.