NIP-XX: window.nostr.content capability for web browsers

[leonacostaok]

NIP-XX: window.nostr.content capability for web browsers

draft | optional | extension of NIP-07

Abstract

This NIP defines a standard interface for browser extensions to expose content-level mute lists to web applications via window.nostr.content. It extends the signer interface defined in NIP-07 and is designed to complement the Web of Trust interface (window.nostr.wot).

While WoT filtering operates on author identity, this NIP operates on content signals — hashtags, keywords, content warnings, languages, and event kinds — independent of who posted them.

---

Motivation

Nostr clients running in web browsers need to filter content based on user-defined rules beyond author trust. Today each client must implement its own mute logic, maintain its own lists, and apply its own matching — duplicating work across every client the user touches.

By exposing a common content mute API on window.nostr, any Nostr web client can apply the user's content preferences without reimplementing them. The extension becomes a single source of truth for what the user does not want to see.

---

Relation to Existing NIPs

• NIP-07: This NIP extends window.nostr with a content sub-object. The two capabilities are independent and composable.
• NIP-51: Mute lists (kind:10000) defined in NIP-51 include pubkeys and event IDs. This NIP focuses on the content-signal subset of mute lists (hashtags, keywords, content warnings, languages, kinds) and does not duplicate pubkey filtering, which belongs to WoT.
• window.nostr.wot: Identity filtering (who) lives in WoT. Content filtering (what) lives here. Clients SHOULD apply both layers.

---

Detection

Extensions MUST inject window.nostr.content before or at document_start. Clients MUST use the following detection pattern:

function onContentReady(callback) {
  if (window.nostr?.content) {
    callback();
  } else {
    document.addEventListener('nostr-content-ready', callback, { once: true });
  }
}

Extensions MUST dispatch a nostr-content-ready event on document once the API object is available.

---

Data Model

A content mute list contains zero or more entries across these signal types:

Signal Type	Description	Example
hashtags	Lowercase tag values from t tags	"bitcoin", "ai"
keywords	Substring or phrase matches against event content	"giveaway", "OnlyFans"
contentWarnings	Values of content-warning tags	"nudity", "violence"
languages	Values of l tags (BCP-47 codes)	"zh", "es"
kinds	Nostr event kind numbers	30023, 1063
events	Specific event IDs to mute	64-char hex event ID
threads	Root event IDs — mutes the event and all replies	64-char hex event ID

Matching for hashtags, contentWarnings, and languages MUST be case-insensitive. Matching for keywords SHOULD be case-insensitive. Implementations MAY support glob or regex patterns for keywords but MUST document this behavior.

---

API

All methods return Promises. Event objects passed to this API MUST conform to the standard Nostr event structure.

---

getMuteList(): Promise<MuteList>

Returns the user's full content mute list.

const list = await window.nostr.content.getMuteList();
// {
//   hashtags: ["ai", "nft"],
//   keywords: ["giveaway", "click here"],
//   contentWarnings: ["nudity"],
//   languages: ["zh"],
//   kinds: [30023],
//   events: ["a1b2c3..."],
//   threads: ["d4e5f6..."]
// }

Return type:

interface MuteList {
  hashtags: string[];
  keywords: string[];
  contentWarnings: string[];
  languages: string[];
  kinds: number[];
  events: string[];   // specific event IDs (hex)
  threads: string[];  // root event IDs (hex) — mutes entire thread
}

All fields MUST be present. Fields with no entries MUST return empty arrays, not null.

---

isMuted(event: NostrEvent): Promise<MuteResult>

Evaluates a single event against the user's mute list. Returns a result object indicating whether the event is muted and, if so, why.

const result = await window.nostr.content.isMuted(event);
// { muted: true, reason: "hashtag", matched: "ai" }
// { muted: false }

Return type:

interface MuteResult {
  muted: boolean;
  reason?: 'hashtag' | 'keyword' | 'contentWarning' | 'language' | 'kind' | 'event' | 'thread';
  matched?: string | number;
}

• reason and matched MUST be present when muted is true.
• matched contains the specific value that triggered the mute (the hashtag string, keyword string, kind number, event ID, or thread root ID).
• If multiple signals match, implementations SHOULD return the first match in the order: event → thread → kind → hashtag → contentWarning → language → keyword.

---

filterMuted(events: NostrEvent[]): Promise<NostrEvent[]>

Returns the subset of events that are not muted. Muted events are excluded from the result. The order of non-muted events MUST be preserved.

const visible = await window.nostr.content.filterMuted(feedEvents);

This is the primary method for feed-level filtering. Clients SHOULD prefer this over calling isMuted in a loop.

---

getStatus(): Promise<ContentStatus>

Returns the readiness state of the content module.

const status = await window.nostr.content.getStatus();
// { configured: true, muteCount: 12 }

Return type:

interface ContentStatus {
  configured: boolean;
  muteCount: number; // total number of mute entries across all signal types
}

---

Matching Rules

Implementations MUST apply the following matching logic when evaluating an event:

event: Muted if event.id is in events.

thread: Muted if the event is part of a muted thread. An event is part of a muted thread if:

• Its id matches a thread root in threads, OR
• It has an e tag with marker "root" whose value is in threads, OR
• It has an e tag with marker "reply" whose value is in threads (for clients that do not set root markers), OR
• It has an A or a tag referencing a muted thread root (for parameterized replaceable events)

Implementations SHOULD resolve thread membership transitively: if event B is a reply to muted root A, and event C is a reply to B, C MUST also be muted. Clients passing events to filterMuted SHOULD include enough tag context for the extension to determine thread membership. Implementations MAY request that clients pass a rootId hint if thread context cannot be determined from tags alone.

Open question: Should threads accept both event IDs (hex, for kind:1 threads) and NIP-19 naddr coordinates (for kind:30023 long-form articles and other parameterized replaceable events whose replies reference them via a tags)? Restricting to hex event IDs keeps the API uniform but excludes a common thread root type. Accepting coordinates adds complexity but covers the full range of Nostr thread patterns.

kind: Muted if event.kind is in kinds.

hashtag: Muted if any value in the event's t tags matches a hashtag in the mute list (case-insensitive).

contentWarning: Muted if any content-warning tag value matches an entry in contentWarnings (case-insensitive). Events with a content-warning tag present but with an empty value SHOULD be muted if "" is in the contentWarnings list.

language: Muted if any l tag value matches an entry in languages (case-insensitive).

keyword: Muted if the event's content field contains any keyword as a substring (case-insensitive). Implementations MAY also match against tag values.

---

Security Considerations

• Read-only API. Web pages MUST NOT be able to modify the mute list through this API.
• List privacy. The mute list reveals user preferences. Implementations MAY require the page to have prior user consent (e.g., via NIP-07 getPublicKey approval) before returning list contents via getMuteList. isMuted and filterMuted MAY be available without consent since they return less information than the raw list.
• Event and thread ID privacy. Muted event IDs and thread root IDs may reveal which specific content a user found objectionable. Implementations SHOULD apply the same consent gate to events and threads in getMuteList as to other list fields. isMuted and filterMuted MUST still function correctly without exposing raw ID lists to the page.
• No identity signals. This API MUST NOT expose pubkeys. Identity filtering belongs to WoT. If a client passes an event to isMuted, the extension MUST NOT use the event's pubkey field in its evaluation.
• Performance. Implementations SHOULD cache compiled keyword matchers and MUST NOT perform synchronous I/O during evaluation.

---

Error Handling

All methods MUST reject with an Error if called with malformed input (e.g., invalid event structure). Implementations MUST NOT reject when an event simply does not match — return { muted: false } instead.

---

Rate Limiting

Implementations SHOULD enforce per-method rate limits to prevent abuse by malicious pages. Rate-limited requests MUST reject with a descriptive error (e.g., "Rate limited").

---

Example Usage

function onContentReady(callback) {
  if (window.nostr?.content) callback();
  else document.addEventListener('nostr-content-ready', callback, { once: true });
}

onContentReady(async () => {
  const { configured } = await window.nostr.content.getStatus();
  if (!configured) return;

  // Filter a feed in one call
  const visible = await window.nostr.content.filterMuted(feedEvents);

  // Check a single event with reason
  const result = await window.nostr.content.isMuted(event);
  if (result.muted) {
    console.log(`Muted: ${result.reason} → "${result.matched}"`);
  }

  // Combine with WoT for full filtering
  const authors = visible.map(e => e.pubkey);
  const trustedAuthors = new Set(await window.nostr.wot.filterByWoT(authors, 2));
  const feed = visible.filter(e => trustedAuthors.has(e.pubkey));
});

---

Reference Implementation

Authors

• npub1gxdhmu9swqduwhr6zptjy4ya693zp3ql28nemy4hd97kuufyrqdqwe5zfk

[staab]

These sorts of utilities should be built on servers so we can benefit from the same work on non-web clients too

[leonacostaok]

@staab NO!

the whole point of Nostr is giving control back to the final user. are we actually building something different here or not?

i wonder, why do we keep centralizing things and trading privacy for convenience?

the mute list already lives on relays as NIP-51 kind:10000 events, portable, accessible to any client. what this NIP standardizes is how a browser extension exposes that list locally to web clients. the data layer is already cross-client. moreover, allows users to define non-public rules for their choices

if we move matching to a server, that server now sees your mute preferences AND every event you're evaluating. it learns what you find objectionable and what content you consume. that's not a neutral architectural choice, that's a surveillance surface dressed up as convenience

non-web clients should implement matching against the same relay-stored lists natively. a reference server implementation can exist as a complementary tool, but it should never replace the local path. the extension approach keeps evaluation on the user's device, where it belongs

[staab]

I see, so this is about protecting encrypted mutes? That makes sense. In that case, I would suggest using a regular javascript library built on top of something like #2229 to keep the scope of the extension as narrow as possible, and make it less onerous for users to set up (they only need one or two extensions, not one for every use case). Of course, a nostrdb extension might not store decrypted events (since other nostr apps would be able to access them). But maybe a separate interface on the same extension would be better. Anyway, you might chime in on that issue.

[leonacostaok]

wow! that's a great catch!

this is where the three layers actually complement each other rather than compete:

• window.nostr.db (NIP-DB: Add window.nostrdb NIP #2229) handles storage and querying;
• window.nostr.wot (NIP-XX: window.nostr.wot capability for web browsers #2236) handles identity trust (who); and,
• window.nostr.content (NIP-XX: window.nostr.content capability for web browsers #2239) handles content filtering (what)

a single extension could implement all three interfaces on top of a shared nostrdb, which directly addresses your extension fatigue concern. users install one extension, get all three capabilities (i am working on this already)

the window.nostr.* interface is just the standardized way web clients access these capabilities, regardless of what's powering it underneath. the implementation can absolutely use a shared nostrdb layer

whether encrypted or not the mutes must stay local, a server-side library can't evaluate encrypted list entries without decrypting them first, which means either the server holds the key or the feature simply doesn't work for private rules. the extension already has the user's keys and can handle this transparently

---

actually, thinking further, we should be even more conservative about what we expose. getMuteList() returning the raw list to the client is probably too much trust. the cleaner model is to keep the extension as a black box oracle, clients ask isMuted(event) and get back a boolean, they ask isInMyWoT(pubkey) and get back a boolean. they never see the underlying data. that way even the client itself can't reconstruct your mute list or trust graph, only act on the answers. least privilege applied to the browser context

[fiatjaf]

I like the ideas here, but the problem is that normal people don't really install web extensions, so I'm not sure how much effort should be directed to these kinds of features.

Are we aiming at just power users? What is the fallback for when this stuff isn't available?

[leonacostaok]

@fiatjaf i can't speak to adoption numbers, but i don't consider myself a power user. i'm a developer who cares about intuitive design and good UX, and i never look for Desktop apps. i prefer everything pinned in a browser tab, Facebook next to Discord next to WhatsApp, and i think most people do the same. that's exactly why extensions matter

the real problem isn't extensions as a concept, it's that the current ones are inaccessible:

1. Alby requires a PhD to understand
2. nos2x is scary af (sorry)

this isn't a criticism of the effort behind them, it's a diagnosis. the primitives are right, the UX is not

concrete examples of what needs to change:

• human-readable permission labels. instead of "NIP-04 DECRYPT" show "read your messages". instead of "sign event" show "publish post". users should never need to know what a NIP number is to make an informed decision
• simple toggles for common preferences: mute languages, content warnings on/off, trust level as a slider ("only people i follow" to "friends of friends" to "everyone")
• a clean main screen with just the essentials: connected account, which apps have access, a single on/off per app. nothing else visible by default
• advanced configuration buried deep in settings, clearly labeled as such. relay lists, WoT hop counts, cache TTLs, none of that on the main screen
• onboarding that explains what the extension does in one sentence before asking for anything

extensions are already load-bearing infrastructure for a huge chunk of nostr web clients. many clients depend on them directly. the fallback question is valid, but the answer isn't to deprioritize extensions, it's to make them something a normal person can actually install and use without reading documentation

on mobile, clients should lean into PWA patterns so the same extension interfaces work there too, rather than treating mobile as a separate world

the API surface this NIP defines should stay minimal and the extension UI should reflect that. most users should never need to touch the advanced section. the extension should just work

[leonacostaok]

on the fallback question: if no extension is present, clients render unfiltered, exactly as they do today. nothing breaks. the extension is purely additive, clients detect it with a simple window.nostr?.content check and degrade gracefully if it's not there. users without the extension get the current experience, users with it get their preferences applied transparently. zero regression

i actually wrote a comment on the nostrdb NIP (#2229 (comment)) that addresses this more broadly. the client shouldn't have to think about fallback at all. through something like window.nostrdb ?? new SimplePool(), the client just queries and gets back filtered, content-mute & trust-aware events regardless of whether an extension is present or not. the fallback is handled at the infrastructure layer, not scattered across every client implementation

[fiatjaf]

the real problem isn't extensions as a concept

Sorry, the real problem is extensions as a concept. No one installs even ad blockers.

many clients depend on them directly

This is not true and the ecosystem is moving away from depending on extensions everywhere.

on the fallback question: if no extension is present, clients render unfiltered, exactly as they do today

Clients don't do this today. Today each client implements its own algorithm.

If clients already have to do it anyway I'm not sure an extension helps much. I guess it could give more control to the user to use their own extension, but again this would be a very power user feature and would require big changes in the clients codebases to support, aside from users having to install the extensions etc.

through something like window.nostrdb ?? new SimplePool(), the client just queries and gets back filtered

This is crazy because the interfaces here are completely different, and SimplePool is very opinionated and full of quirks, it isn't a lean wrapper in any sense.

All these comments make me think you don't have much experience with Nostr and developing Nostr clients at this point, so maybe we should wait a little longer to review these proposals.

[leonacostaok]

you are right. i only have two weeks working on it. i don't have knowledge of every implementation, the evolution of the different tools, and what different clients, relays and developers are using vs what they were using.

i am pointing out to a few structural issues that systematically centralize the ecosystem more and more, but you already know that: https://fiatjaf.com/87a208d9.html