API расширения
Расширение предоставляет window.nostr для идентификации, подписи событий и шифрования сообщений NIP-04/NIP-44.
Установите расширение, выберите аккаунт и подключите сайт по запросу. Для подписи и шифрования нужен аккаунт с возможностью подписи; может потребоваться разблокировать хранилище. Для чтения известного публичного ключа разблокировка не нужна.
Настройка
Перед вызовом проверьте наличие нужного метода. Наличие провайдера не означает, что сайт подключён или запрос одобрен.
// 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 подписи NIP-07
Расширение реализует API подписи NIP-07 через window.nostr.
getPublicKey()
Возвращает публичный ключ активного аккаунта в шестнадцатеричном формате. Необходимы подключение сайта и доступ к идентификации.
Возвращаемое значение
Promise<string>
Пример
const pubkey = await window.nostr.getPublicKey();
console.log(pubkey); // "3bf0c63f..."signEvent(event)
Подписывает событие и добавляет id, pubkey и sig. Передайте created_at самостоятельно; подписывающее приложение сохраняет эту метку времени. Если указан pubkey, он должен соответствовать активному аккаунту. Подпись не публикует событие.
Параметры
| Имя | Тип | Описание |
|---|---|---|
event | UnsignedEvent | Событие с kind, content, tags и created_at (время Unix в секундах) |
Возвращаемое значение
Promise<SignedEvent>
Пример
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)
Шифрует сообщение с помощью NIP-04, устаревшего формата шифрования личных сообщений.
Параметры
| Имя | Тип | Описание |
|---|---|---|
pubkey | string | Публичный ключ получателя: 64 шестнадцатеричных символа |
plaintext | string | Сообщение для шифрования |
Возвращаемое значение
Promise<string>
Пример
const encrypted = await window.nostr.nip04.encrypt(
recipientPubkey,
"Secret message"
);nip04.decrypt(pubkey, ciphertext)
Расшифровывает сообщение NIP-04.
Параметры
| Имя | Тип | Описание |
|---|---|---|
pubkey | string | Публичный ключ отправителя: 64 шестнадцатеричных символа |
ciphertext | string | Строка зашифрованного сообщения |
Возвращаемое значение
Promise<string>
Пример
const plaintext = await window.nostr.nip04.decrypt(
senderPubkey,
ciphertext
);
console.log(plaintext); // "Secret message"nip44.encrypt(pubkey, plaintext)
Шифрует сообщение с помощью NIP-44. В примере используется стандартный вызов с двумя аргументами.
Параметры
| Имя | Тип | Описание |
|---|---|---|
pubkey | string | Публичный ключ получателя: 64 шестнадцатеричных символа |
plaintext | string | Сообщение для шифрования |
Возвращаемое значение
Promise<string>
Пример
const encrypted = await window.nostr.nip44.encrypt(
recipientPubkey,
"Secret message"
);nip44.decrypt(pubkey, ciphertext)
Расшифровывает сообщение NIP-44.
Параметры
| Имя | Тип | Описание |
|---|---|---|
pubkey | string | Публичный ключ отправителя: 64 шестнадцатеричных символа |
ciphertext | string | Строка зашифрованного сообщения |
Возвращаемое значение
Promise<string>
Пример
const plaintext = await window.nostr.nip44.decrypt(
senderPubkey,
ciphertext
);
console.log(plaintext); // "Secret message"getRelays()
Возвращает URL реле, настроенных в расширении. У каждой записи read: true и write: true. Метод не получает политики реле NIP-65 аккаунта и может вернуть пустой объект.
Возвращаемое значение
Promise<Record<string, { read: boolean; write: boolean }>>
Пример
const relays = await window.nostr.getRelays();
// {
// "wss://relay.damus.io": { read: true, write: true },
// "wss://nos.lol": { read: true, write: true }
// }Подключение, разрешения и ошибки
Вызовы возвращают промисы и могут завершиться ошибкой при отказе пользователя, отключении сайта, запрете доступа к идентификации или истечении времени ожидания. Аккаунты только для чтения не могут подписывать и шифровать.
Смена аккаунта может отменить ожидающий запрос. Время ожидания вызова со страницы составляет 120 секунд, включая ожидание подключения, разрешения или разблокировки. Обрабатывайте ошибки и позволяйте повторить запрос; тексты ошибок не являются стабильными машинными кодами.
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 };
}
}Используйте SDK для запросов к графу подписок и API WoT Oracle для сведений о публичных списках заглушённых пользователей. Эти сведения отделены от расстояния в графе подписок и не образуют общую оценку доверия. Расширение предоставляет идентификацию и подпись.
Кошелёк расширения через WebLN
Перед операциями вызовите enable(). sendPayment() принимает счёт BOLT11 и возвращает прообраз после успешной оплаты. Доступны также getInfo(), makeInvoice() и getBalance(); проверяйте наличие этих необязательных возможностей.
Пример
// 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);
}Примечания по интеграции
Подключение Nostr не разрешает доступ к кошельку. Пользователь должен настроить кошелёк и может получить запрос на одобрение платежа. Не отправляйте дубликаты и показывайте статус. После тайм-аута сначала проверьте результат в кошельке.
Что доступно веб-сайтам
window.nostr предоставляет NIP-07-идентификацию, подпись и поддерживаемое шифрование; window.webln предоставляет кошелёк. Проверяйте наличие необязательных методов. Passkey, seed и удалённые аккаунты используют общий интерфейс для сайтов.
Примечания по интеграции
Хранилище, файлы восстановления, архив и внутренние RPC не являются публичными API сайтов. Приложению не нужен seed. Аккаунты только для чтения не подписывают; удалённый подписант может запросить внешнее одобрение. Для доверия используйте граф SDK и Oracle.
Подпись, публикация и результаты
Подпись и публикация выполняются отдельно. Получите подписанное событие через NIP-07, затем отправьте на выбранные реле. Пример возвращает результат приёма каждым реле и закрывает временный пул.
Пример
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);
}
}Примечания по интеграции
Подпись подтверждает авторство, не доставку. Показывайте успех только после приёма реле. Сохраняйте частичные успехи и повторно отправляйте то же подписанное событие с тем же ID. В постоянном приложении используйте существующие соединения.
Разрешения и смена аккаунта
Запрашивайте публичный ключ кнопкой подключения, а подписи соответствующим действием. Расширение может запросить соединение, разблокировку или одобрение. Старое разрешение не распространяется автоматически на другой аккаунт.
Пример
// 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.Примечания по интеграции
Событие смены аккаунта специфично для Nostr WoT. Проверяйте идентичность перед важными действиями и отбрасывайте устаревшие ответы. Обрабатывайте отказ, сохраняйте черновик и предлагайте повтор. Не запускайте отменённые запросы автоматически. HTTP использует тип 27235, AUTH реле — 22242.