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.
7.4 KiB
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. Seedocs/dev/nostr.mdfor the Deno setup.strfry-policy.ts— the relay's own write policy.ldap-only-policy.ts— the member bridge'spluginDown.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.mjssync-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":
typemust benew.- Event must be well-formed (
pubkey, integerkind,tagsarray). kindmust be in the allowlist (deny by default).contentmust be within the byte bound.- Tag count must be within bounds.
p-tag count must be within the hellthread bound.- Per-IP token bucket (keyed on
sourceInfo). - Per-author token bucket (keyed on
event.pubkey). - 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