API da extensão
A extensão expõe window.nostr para identidade, assinatura de eventos e criptografia de mensagens NIP-04/NIP-44.
Instale a extensão, selecione uma conta e conecte seu site quando solicitado. Assinatura e criptografia exigem uma conta capaz de assinar e podem pedir o desbloqueio do cofre. Ler uma chave pública conhecida não exige desbloqueá-lo.
Configuração
Verifique se o método necessário existe antes de chamá-lo. A presença do provedor não significa que o site está conectado ou que uma solicitação foi autorizada.
// 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 assinatura NIP-07
A extensão implementa a API de assinatura NIP-07 por meio de window.nostr.
getPublicKey()
Retorna a chave pública hexadecimal da conta ativa. Exige conexão do site e acesso à identidade.
Retorno
Promise<string>
Exemplo
const pubkey = await window.nostr.getPublicKey();
console.log(pubkey); // "3bf0c63f..."signEvent(event)
Assina o evento e acrescenta id, pubkey e sig. Forneça created_at; o assinador preserva esse horário. Se fornecer pubkey, ela deve corresponder à conta ativa. Assinar não publica o evento.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
event | UnsignedEvent | Evento com kind, content, tags e created_at (tempo Unix em segundos) |
Retorno
Promise<SignedEvent>
Exemplo
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)
Criptografa uma mensagem com NIP-04, o formato antigo de criptografia de mensagens diretas.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
pubkey | string | Chave pública do destinatário com 64 caracteres hexadecimais |
plaintext | string | Mensagem a criptografar |
Retorno
Promise<string>
Exemplo
const encrypted = await window.nostr.nip04.encrypt(
recipientPubkey,
"Secret message"
);nip04.decrypt(pubkey, ciphertext)
Descriptografa uma mensagem NIP-04.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
pubkey | string | Chave pública do remetente com 64 caracteres hexadecimais |
ciphertext | string | Texto da mensagem criptografada |
Retorno
Promise<string>
Exemplo
const plaintext = await window.nostr.nip04.decrypt(
senderPubkey,
ciphertext
);
console.log(plaintext); // "Secret message"nip44.encrypt(pubkey, plaintext)
Criptografa uma mensagem com NIP-44. Este exemplo usa a chamada padrão com dois argumentos.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
pubkey | string | Chave pública do destinatário com 64 caracteres hexadecimais |
plaintext | string | Mensagem a criptografar |
Retorno
Promise<string>
Exemplo
const encrypted = await window.nostr.nip44.encrypt(
recipientPubkey,
"Secret message"
);nip44.decrypt(pubkey, ciphertext)
Descriptografa uma mensagem NIP-44.
Parâmetros
| Nome | Tipo | Descrição |
|---|---|---|
pubkey | string | Chave pública do remetente com 64 caracteres hexadecimais |
ciphertext | string | Texto da mensagem criptografada |
Retorno
Promise<string>
Exemplo
const plaintext = await window.nostr.nip44.decrypt(
senderPubkey,
ciphertext
);
console.log(plaintext); // "Secret message"getRelays()
Retorna os URLs dos relays configurados na extensão. Cada entrada tem read: true e write: true. Este método não consulta as políticas de relays NIP-65 da conta e pode retornar um objeto vazio.
Retorno
Promise<Record<string, { read: boolean; write: boolean }>>
Exemplo
const relays = await window.nostr.getRelays();
// {
// "wss://relay.damus.io": { read: true, write: true },
// "wss://nos.lol": { read: true, write: true }
// }Conexão, permissões e erros
As chamadas retornam promessas e podem falhar se o usuário recusar, o site estiver desconectado, o acesso à identidade estiver desativado ou o tempo se esgotar. Contas somente leitura não podem assinar nem criptografar.
Uma troca de conta pode invalidar uma solicitação pendente. As chamadas da página expiram após 120 segundos, incluindo a espera por conexão, permissão ou desbloqueio. Trate os erros e permita tentar novamente; as mensagens de erro não são códigos estáveis para processamento 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 };
}
}Use o SDK para consultar o grafo de seguidores e a API WoT Oracle para consultar silenciamentos públicos. Essas informações ficam separadas da distância no grafo e não geram uma pontuação de confiança combinada. A extensão fornece identidade e assinatura.
Usar a carteira da extensão com WebLN
Chame enable() antes das operações. sendPayment() recebe uma fatura BOLT11 e retorna uma pré-imagem após o pagamento. A extensão também oferece getInfo(), makeInvoice() e getBalance(); detecte essas capacidades opcionais.
Exemplo
// 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 integração
Uma conexão Nostr não autoriza a carteira. O usuário precisa configurá-la e pode ter de aprovar o pagamento. Evite envios duplicados e mostre o estado. Após um timeout, confira primeiro o resultado na carteira antes de tentar novamente.
O que os sites podem usar
window.nostr expõe identidade NIP-07, assinaturas e cifragem disponível; window.webln expõe a carteira. Detecte métodos opcionais. Contas com passkey, semente ou assinador remoto compartilham a interface para sites.
Notas de integração
Cofre, arquivos de recuperação, arquivo de eventos e RPCs internos não são APIs públicas de sites. O app não precisa da semente. Contas somente leitura não assinam; assinadores remotos podem exigir aprovação externa. Use grafo do SDK e Oracle para consultas de confiança.
Assinar, publicar e mostrar resultados
Assinatura e publicação são etapas separadas. Obtenha o evento assinado via NIP-07 e envie aos relays escolhidos. O exemplo retorna aceitação por relay e fecha seu pool temporário.
Exemplo
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 integração
A assinatura prova autoria, não entrega. Mostre sucesso apenas onde houve aceitação. Preserve sucessos parciais e reutilize evento assinado e ID nas novas tentativas. Em apps persistentes, reutilize o transporte relay existente.
Permissões e troca de conta
Peça a chave pública pelo botão Conectar e assinaturas pela ação correspondente. A extensão pode pedir conexão, desbloqueio ou aprovação. Uma permissão anterior não cobre automaticamente outra conta ou operação.
Exemplo
// 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 integração
O evento de troca de conta é específico do Nostr WoT. Confira a identidade antes de ações sensíveis e descarte respostas antigas. Capture recusas, preserve o rascunho e ofereça nova tentativa. Não repita automaticamente prompts cancelados. HTTP usa tipo 27235; AUTH de relay usa 22242.