tessera-kit

import {
  memberKey,
  buildMembershipFilter,
  serializeFilter,
  signFilterBlob,
} from '@forgesworn/tessera-kit'

const epoch = Math.floor(Date.now() / 1000)

// (a) OPEN pool — opt-in-public members (public figures), discoverable by anyone
//     holding their pubkey. memberKey(pk) inserts the pubkey itself.
const openValues = openMemberPubkeys.map((pk) => memberKey(pk))
const openFilter = buildMembershipFilter(openValues, { epoch })

// (b) KEYED pool — everyone else. memberKey(pk, salt) inserts H(salt ‖ pk), so a
//     stranger needs the out-of-band salt to compute the value to test. (This is
//     a speed-bump, not a boundary — see SECURITY.md.) Passing `salt` only sets
//     the on-wire `keyed` flag; the caller does the salting via memberKey.
const salt = serverKeyedSaltHex // distributed out-of-band; NEVER in the blob
const keyedValues = keyedMemberPubkeys.map((pk) => memberKey(pk, salt))
const keyedFilter = buildMembershipFilter(keyedValues, { epoch, salt })

// Serialize to the KFLT blob, then sign it in place with the SERVER key, BOUND
// to this deployment's `context` — the stable address a verifier already knows
// out-of-band (e.g. a kindred d-tag `kindred:members:<ns>:<serverId>`; see
// PROTOCOL.md §4.1/§4.3). The signature binds provenance AND this context: a
// tampered or attacker-authored blob is detectable, and a blob signed for one
// deployment cannot be replayed as another's, even under a reused signing key.
//
// ⚠️ `namespace` MUST NOT contain a colon (`serverId` may) — the d-tag is
// parsed by splitting on the FIRST colon after "kindred:members:", so a
// colon in `namespace` lets two different (namespace, serverId) pairs
// collide on the same context string. See PROTOCOL.md §4.3/§6.
const context = `kindred:members:${namespace}:${serverId}`
const blob = serializeFilter(openFilter)
signFilterBlob(blob, serverPrivHex, context) // mutates `blob`: writes signer pubkey + sig

// Publish `blob` however you like — HTTPS, or a Nostr kind-30444 event
// (see PROTOCOL.md "Server publication shape" for the zero-dependency tag layout).

import { verifyAndParseFilter, testMembership, memberKey } from '@forgesworn/tessera-kit'

// One call does the mandatory work: pin-verify the signer AND context, parse,
// and (if you pass minEpoch) reject a stale/rolled-back blob. `context` MUST be
// the SAME stable deployment address the server signed with (see above) — track
// the highest epoch you've accepted per (pinnedPubkeyHex, context) and pass it
// back in next time.
//
// ⚠️ Build `context` from the (namespace, serverId) YOU chose to fetch —
// `namespace`/`serverId` here are values the client already had BEFORE
// fetching anything (that's how it picked which event to ask for). NEVER
// read the `d`-tag (or any other tag) off the event you just received and
// use THAT to build `context` — a relay/MITM controls every tag on the
// event it serves you, so trusting a tag-derived context lets it swap in a
// different server's validly-signed blob and have your own code "confirm"
// the substitution for it. See PROTOCOL.md §4.3/§6.
const filter = verifyAndParseFilter(blob, {
  pinnedPubkeyHex: PINNED_SERVER_PUBKEY,
  context: `kindred:members:${namespace}:${serverId}`,
  minEpoch: lastSeenEpoch, // optional; omit on first fetch
})
// filter.epoch is the blob's own SIGNED epoch — use THIS for freshness, never a
// Nostr ["epoch"] tag on a wrapping event (that tag is signed only by the
// publisher key and is never cross-checked against the blob; see PROTOCOL.md §4.3/§6).

// Now a local membership test. Transform the query the SAME way the pool was
// built: memberKey(friendPk) for an open pool, memberKey(friendPk, salt) keyed.
const present = testMembership(filter, memberKey(friendPubkey))
// `present === true` is a CANDIDATE, not a proof — at ecosystem scale ~1.5 false
// hits accumulate per full sweep at 16-bit (PROTOCOL.md §7.2). Confirm on connect
// (a key-control challenge) before acting on a hit.

import { issuePresenceCapability, testWithCapability } from '@forgesworn/tessera-kit/capability'

// Subject (the friend) issues a capability for a colon-free serverId. `salt` is
// the KEYED pool's salt — pass it for a keyed server, omit it for an open one.
// The salt itself never ends up on the returned capability; only the subject's
// own derived `memberValue` does.
const cap = issuePresenceCapability(
  { serverId: 'play.example.com', subjectPubHex, salt, expiresAt },
  subjectPrivHex,
)

// Bearer tests it. Expiry + signature are checked BEFORE the membership test;
// an expired/forged capability THROWS (it is not a silent `false`).
const friendPresent = testWithCapability(keyedFilter, cap)

import { buildFilterPublication, decodeFilterPublicationContent } from '@forgesworn/tessera-kit/nostr'

// Server: assemble the unsigned Nostr event template around a signed KFLT blob.
// tessera-kit does NOT know kindred's addressing convention (the protocol
// naming — see PROTOCOL.md §6) — YOU supply kind/tags.
const event = buildFilterPublication({ kind: 30444, tags: [['d', 'my:d:tag']], blob, createdAt })
// event.content is base64(blob); sign `event` with your own Nostr key (NIP-01) — separate
// from the in-blob Schnorr provenance signature (signFilterBlob).

// Client: decode an event's content back to the raw blob, capped at KFLT_MAX_BLOB_BYTES
// (or a smaller caller-supplied cap) BEFORE decoding, so a hostile oversized event can't
// force a large allocation.
const blobBytes = decodeFilterPublicationContent(event.content)