Files
raucao 023f5b39bf
CI / Test (pull_request) Successful in 43s
Release Drafter / Update release notes draft (pull_request) Successful in 3s
Fix strfry README and drop deployment specifics
The new README described the directory as mostly Node ESM and called the
pre-existing Deno policies "legacy", even though ldap-policy.ts is a shared
module reused by the new member bridge and strfry-policy.ts is the members
relay's current write policy. It also baked in internal deployment details
(Chef, strfry-1, /etc/*.conf paths, the staging relay's ZeroTier IP).

Document every file with its correct runtime (Deno vs Node 24 LTS), drop the
"legacy" label, and genericize the deployment examples. Cross-link the README
from docs/dev/nostr.md, and replace the remaining internal host/IP references
in sync-policy.mjs and its test with neutral placeholders.
2026-11-18 13:51:48 +04:00
..
2025-05-21 16:42:49 +04:00

strfry policies

Policy plugins for the Kosmos strfry relays. There are two runtimes in this directory:

  • Deno — the members relay's write policy and member bridge, plus the manual member-note sync. Dependencies are pinned in deno.json/deno.lock. See docs/dev/nostr.md for the Deno setup.
    • strfry-policy.ts — the relay's own write policy.
    • ldap-only-policy.ts — the member bridge's pluginDown.
    • ldap-policy.ts — shared LDAP membership module used by both of the above.
    • strfry-sync.ts — manual member-note sync tool.
  • Node (plain ESM .mjs, Node 24 LTS, no dependencies) — the submission relay and the approved-content sync.
    • submission-policy.mjs
    • sync-policy.mjs

In development the whole directory is mounted at /opt/strfry (see the strfry service in docker-compose.yml, and docker/strfry/strfry.conf for the write-policy wiring); in production the ops tooling deploys it to the relay hosts.

How strfry invokes a policy

strfry spawns the configured relay.writePolicy.plugin command and talks to it over stdin/stdout. Each line on stdin is a JSON object:

{"type":"new","event":{...},"receivedAt":1700000000,"sourceType":"IP4","sourceInfo":"203.0.113.7"}

sourceType is one of IP4, IP6, Import, Stream, Sync, Stored. sourceInfo is an IP address (for IP4/IP6) or a relay URL (for Sync/Stream).

For every input line the plugin must write one line of JSON to stdout:

{"id":"<event id>","action":"accept|reject","msg":"..."}

msg is only meaningful for reject and is returned to the client. Diagnostics go to stderr and end up in the strfry log.

submission-policy.mjs

Write policy for the public submission relay. Open to all authors — there is no LDAP/membership check. It applies only the "usual gates":

  1. type must be new.
  2. Event must be well-formed (pubkey, integer kind, tags array).
  3. kind must be in the allowlist (deny by default).
  4. content must be within the byte bound.
  5. Tag count must be within bounds.
  6. p-tag count must be within the hellthread bound.
  7. Per-IP token bucket (keyed on sourceInfo).
  8. Per-author token bucket (keyed on event.pubkey).
  9. Short-window content dedupe (sha256 of content, skipped for content shorter than the configured minimum so empty kind-3/kind-5 content is not falsely deduped).

All state is in-memory and resets whenever strfry reloads the plugin (e.g. on file mtime change or config change).

Environment variables

Variable Default Description
SUBMISSION_KINDS 0,3,5,360,30360 Comma-separated kind allowlist. Empty value denies every kind.
SUBMISSION_MAX_CONTENT_LENGTH 16384 Max content size in UTF-8 bytes.
SUBMISSION_MAX_TAGS 200 Max number of tags per event.
SUBMISSION_MAX_P_TAGS 10 Max number of p tags (hellthread cap).
SUBMISSION_IP_BURST 120 Per-IP bucket capacity (burst).
SUBMISSION_IP_REFILL_PER_SEC 5 Per-IP sustained refill rate.
SUBMISSION_AUTHOR_BURST 10 Per-author bucket capacity (burst).
SUBMISSION_AUTHOR_REFILL_PER_SEC 0.2 Per-author sustained refill rate.
SUBMISSION_DEDUPE_WINDOW_MS 60000 Dedupe window.
SUBMISSION_DEDUPE_MIN_LENGTH 50 Minimum content length that is deduped.

strfry configuration

relay {
    writePolicy {
        plugin = "node /opt/strfry/submission-policy.mjs"
    }
}

sync-policy.mjs

Write policy for the approved-content sync on the members relay. It runs under a separate strfry config that shares the relay's database, and it is fail-closed and does source verification only; all content gating (kinds, sizes, rates, …) is handled by the other policies. An event is accepted only when all of the following hold:

  • type === "new";
  • sourceType === "Sync";
  • sourceInfo === STAGING_RELAY_URL (byte-exact).

Everything else is rejected, and the log line records the observed vs expected sourceType and sourceInfo. If STAGING_RELAY_URL is unset, the policy rejects every event.

Environment variables

Variable Default Description
STAGING_RELAY_URL (unset) Expected sourceInfo for synced events, e.g. ws://staging-relay:7779. Unset/empty rejects everything. Whitespace around the configured value is trimmed; sourceInfo is compared as-is.

strfry configuration

relay {
    writePolicy {
        plugin = "node /opt/strfry/sync-policy.mjs"
    }
}

The matching sync is driven by strfry --config <sync-config> sync ws://<staging-relay>:7779 --dir down, which sets sourceType=Sync and sourceInfo to the relay URL passed on the command line. STAGING_RELAY_URL must be that exact URL.

strfry-policy.ts

Deno write policy for the members relay itself. It combines the hellthread cap, anti-duplication (via Deno KV with a 60s window), and the shared LdapPolicy membership check, but lets NIP-46 (kind 24133) ephemeral events through from anyone. See docs/dev/nostr.md for the Deno requirements and configuration.

ldap-only-policy.ts

Deno write policy for the members relay's member bridge — a strfry router stream group (dir = "down") that subscribes to the local submission relay and writes member-authored events into the members relay's database. It is this stream group's pluginDown, and it accepts an event only when its author is an LDAP member (or a whitelisted pubkey).

It reuses ldap-policy.ts and the shared .env (the same read-only LDAP service account as strfry-policy.ts), but deliberately does no hellthread/anti-duplication work and opens no Deno KV store — so it can run alongside the relay's own policy process without shared state.

strfry configuration

streams {
    members {
        dir = "down"
        filter = { "kinds": [0, 3, 5, 360, 30360] }
        urls = [ "ws://<submission-relay>:7778" ]
        pluginDown = "/opt/strfry/ldap-only-policy.ts"
    }
}

driven by strfry router <member-bridge-config>. dir = "down" keeps it strictly one-way (the router never watches or forwards the local DB). The filter bounds the LDAP lookups to the submission kinds; membership is decided per event by the policy, so no member list is maintained.

ldap-policy.ts

Shared Deno module exporting LdapConfig and the LdapPolicy class: it looks up the event author's nostrKey in LDAP (with a pubkey whitelist and special handling for zap receipts) and rejects non-members. Imported by both strfry-policy.ts and ldap-only-policy.ts.

strfry-sync.ts

Deno script for one-off/manual syncs of all notes authored by local users (any account that has verified its Nostr pubkey with akkounts) from a remote relay via negentropy sync. See the "Manual tasks" section in docs/dev/nostr.md.

Tests

Unit tests use the built-in node:test runner (no dependencies):

node --test extras/strfry/test/*.test.mjs

Smoke test

printf '%s\n' \
  '{"type":"new","sourceType":"IP4","sourceInfo":"1.2.3.4","event":{"id":"a","pubkey":"b","kind":360,"tags":[],"content":"hi"}}' \
  | ./submission-policy.mjs

printf '%s\n' \
  '{"type":"new","sourceType":"Sync","sourceInfo":"ws://staging-relay:7779","event":{"id":"a","pubkey":"b","kind":360,"tags":[],"content":"hi"}}' \
  | STAGING_RELAY_URL='ws://staging-relay:7779' ./sync-policy.mjs