Nostr WoT

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.

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

javascript
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

NomeTipoDescrição
eventUnsignedEventEvento com kind, content, tags e created_at (tempo Unix em segundos)

Retorno

Promise<SignedEvent>

Exemplo

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)

Criptografa uma mensagem com NIP-04, o formato antigo de criptografia de mensagens diretas.

Parâmetros

NomeTipoDescrição
pubkeystringChave pública do destinatário com 64 caracteres hexadecimais
plaintextstringMensagem a criptografar

Retorno

Promise<string>

Exemplo

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

nip04.decrypt(pubkey, ciphertext)

Descriptografa uma mensagem NIP-04.

Parâmetros

NomeTipoDescrição
pubkeystringChave pública do remetente com 64 caracteres hexadecimais
ciphertextstringTexto da mensagem criptografada

Retorno

Promise<string>

Exemplo

javascript
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

NomeTipoDescrição
pubkeystringChave pública do destinatário com 64 caracteres hexadecimais
plaintextstringMensagem a criptografar

Retorno

Promise<string>

Exemplo

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

nip44.decrypt(pubkey, ciphertext)

Descriptografa uma mensagem NIP-44.

Parâmetros

NomeTipoDescrição
pubkeystringChave pública do remetente com 64 caracteres hexadecimais
ciphertextstringTexto da mensagem criptografada

Retorno

Promise<string>

Exemplo

javascript
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

javascript
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.

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

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

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

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.

Referência e opções adicionais

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.

terminal
$npm install nostr-tools

Exemplo

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

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

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.

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.