bitgate/docs/TODO.md

BitGate — open items

Updated: 2026-08-10

BitGate is the standalone governance and policy engine in this repository. The existing @bitgate/core, @bitgate/nostr, @bitgate/runtime, @bitgate/verify, @bitgate/testing, @bitgate/widget, and compatibility packages are existing surfaces. The distribution and API work below must be additive and must not break current BitGate consumers or the behavior characterized from BitVid and BitRoad.

Priority 1 — Distribution

• Guarantee one browser-ready standalone build: bitgate.js.
  • Require no npm at runtime.
  • Require no runtime dependencies.
  • Work directly from vanilla HTML.
• Publish predictable downloadable release artifacts.
• Provide both an ES module and an npm package.
• Verify the standalone build works from ordinary static HTTPS hosts and localhost development without requiring a framework or bundler.
• Document file:// limitations and the recommended local development server path.

Priority 2 — Canonical API

• Establish one obvious entry point, for example:

  const decision = await gate.evaluate({
    viewer,
    item,
    action: "view"
  });
  

• Standardize decision output:

  {
    visibility,
    ranking,
    interaction,
    transaction,
    reasons,
    evidence
  }
  

• Keep the four decision axes independent:

  • visibility
  • ranking
  • interaction
  • transaction

• Do not collapse all policy outcomes into allowed/blocked.

• Define stable machine-readable reason codes, for example:

  • USER_MUTED
  • FOLLOWED_USER_REPORTED
  • MALWARE_SIGNAL
  • SPAM_SIGNAL
  • POLICY_BLOCK

• Define how any legacy adapter verdicts map onto the canonical four-axis decision without losing information.

• Define deterministic behavior when an axis is not applicable to an action, such as transaction policy for a read-only view.

Priority 3 — Shared Context

• Accept a standardized viewer context:

  {
    pubkey,
    follows,
    mutes,
    relays,
    trustGraph,
    interests
  }
  

• Avoid requiring BitGate-specific conversions when data already comes from BitLogin or Nostr.

• Define optional versus required context fields and safe defaults for missing, stale, or unavailable context.

• Keep context normalization separate from policy evaluation so applications can pass through native BitLogin/Nostr structures without needless copying.

• Define privacy boundaries for context: do not require raw viewer identity, cross-site tracking data, or unnecessary behavioral history.

Priority 4 — Policies

• Formalize the bitgate/1 policy schema.
• Make policies serializable, hashable, signable, publishable, and forkable.
• Allow policies to be loaded from signed Nostr events.
• Verify policy signatures, schema versions, hashes, and issuer metadata before using a policy; fail safely when verification is ambiguous.
• Support named policy profiles, for example:
  • social
  • comments
  • marketplace-browse
  • marketplace-checkout
  • messaging
• Keep app-specific policy configuration outside the core engine.
• Define policy precedence, composition, conflict resolution, and explicit override rules when multiple policies apply.
• Make policy evaluation deterministic and testable for the same input, policy set, and evaluation time.
• Document policy expiry, revocation, cache behavior, and offline behavior.

Priority 5 — Explainability

• Make every decision explainable.
• Return machine-readable reasons.
• Return optional human-readable explanations without making UI copy part of the stable machine contract.
• Support gate.explain(decision).
• Make it straightforward for applications to answer:
  • “Why was this hidden?”
  • “Why can't I reply?”
  • “Why is checkout disabled?”
• Include enough evidence references to audit a decision without exposing unnecessary private viewer data.
• Distinguish the policy reason, the evidence source, and the resulting action; do not imply that a signal is proof when it is only a heuristic.
• Define stable explanation behavior for conflicting signals, unavailable evidence, expired policies, and fail-open/fail-closed choices.

Priority 6 — Documentation

• Add a vanilla HTML example.
• Add a BitLogin + BitGate example.
• Add a social feed example.
• Add a commerce example.
• Document the difference between:
  • hide
  • downrank
  • warn
  • interaction deny
  • transaction deny
• Document the canonical API in relation to the existing package APIs and how current consumers migrate without a forced rewrite.
• Document the security and privacy boundaries of local policy evaluation, signed Nostr policies, and remotely supplied evidence.

Compatibility and testing gates

• Preserve existing package APIs while introducing the canonical BitGate API.
• Preserve the behavior characterized from BitVid and BitRoad during extraction and future policy-engine changes.
• Add unit tests for canonical decision-axis independence, stable reason codes, legacy verdict mapping, policy precedence, and explainability.
• Add tests for signed policy verification, malformed policies, unknown schema versions, expired policies, and ambiguous evidence.
• Add browser integration tests for the standalone bitgate.js artifact from vanilla HTML.
• Test the npm package and ES-module import paths from a clean consumer project.
• Test the definition-of-done examples against the published artifact.
• Run the existing build, typecheck, and test suite before and after changes; standalone work must not replace or mutate current package output.

Definition of done

A developer can drop bitgate.js into a page, pass it a viewer, item, and action, and receive a consistent, explainable policy decision without needing to understand BitGate internals. The same canonical engine is available as an ES module and npm package, while existing BitGate consumers continue to work unchanged.

Open design decisions

• Choose the exact bitgate/1 event kind and signed-policy event format.
• Choose the canonical TypeScript types and runtime validation strategy.
• Decide whether gate.explain(decision) is pure/local only or may resolve additional evidence asynchronously.
• Decide default fail-open/fail-closed behavior per axis and per action.
• Decide how policy profile discovery works without creating a centralized authority or leaking private application context.
• Decide whether standalone output is generated from the canonical engine directly or from a separately maintained browser entry point.
• Decide how browser builds expose version and integrity metadata.

BitBlocks App Kit compatibility layer

Do this only after BitLogin, BitGate, and BitFeed each have clean standalone APIs. BitBlocks is an optional integration layer, not a replacement for any of the three libraries. It must not merge their implementations or make an app depend on the kit when it only needs BitGate.

• Create a tiny optional BitBlocks integration layer.

• Keep BitLogin, BitGate, and BitFeed as separate replaceable libraries; the App Kit must compose them rather than absorb them.

• Provide shared initialization, for example:

  const app = await BitBlocks.create({
    login: {},
    gate: {},
    feed: {},
    relays: [...]
  });
  

• Standardize the viewer context exchanged between the components without changing BitGate's policy engine, signed-policy format, or four-axis decision contract.

• Centralize optional common Nostr plumbing in the kit: relay connections, subscriptions, EOSE handling, reconnects, deduplication, timeouts, publishing, OK responses, profile lookup, follow-list lookup, and mute-list lookup.

• Expose app.viewer, app.signer, app.relays, app.gate, and app.feed through documented interfaces.

• Keep each underlying library independently usable and independently versioned.

• Do not make applications depend on BitBlocks when they use only BitGate's policy and governance capabilities.

• Add integration tests proving the kit is an adapter over the standalone APIs, not a second implementation of identity, policy, or feed logic.

BitBlocks definition of done

A developer or AI agent can take bitlogin.js, bitgate.js, bitfeed.js, and bitblocks.js and build a functional static Nostr application with almost no infrastructure or integration boilerplate, while each individual library remains usable without BitBlocks.

Feedback from Tessera building a moderation layer (2026-08-11)

Tessera needed exactly what BitGate provides (moderation as policy over public Nostr events) but ended up building a client-side stand-in — a kind-33604 "moderation decision" event carrying the four dimensions, ladder-max composition, a signed root-controlled moderator set, and a browser console — rather than integrating @bitgate/*. Notes on why, and what would have made adoption the obvious choice.

Why we didn't reach for BitGate first

• [ADDRESSED 2026-08-11] No obvious "just the engine + events over Nostr" path for a static site. The headless path existed but was buried under the widget on-ramp. Added a "Headless, straight from NIP-32 labels" subsection to the README (four pure functions: decode → contributions → reduce → evaluate, no runtime transport, no DOM) and a runnable examples/headless-quickstart.mjs. Pinned by tests/headless-quickstart.test.js.
• [ADDRESSED 2026-08-11] The decision event format is ours, not yours. There was no need to invent 33604: NIP-32 label events (kind 1985) are the canonical signed decision format — @bitgate/nostr already has the codec (encodeLabel/decodeLabels/labelsToContributions) and docs/labels.md documents interop. The README and the headless example now say so explicitly and round-trip real 1985 events into a four-dimension decision, so other clients interoperate instead of each inventing a shape.

High-value asks

• [DONE 2026-08-11] Headless quickstart: shipped examples/headless-quickstart.mjs and a README subsection — @bitgate/core composing a decision from an array of kind-1985 label events + an honored moderator set + a policy, zero DOM. It shows exactly the transaction-dimension case the ask names: a malware plugin stays visible (warn) but not installable (transaction deny) — where a hidden boolean can't reach. Pinned by tests/headless-quickstart.test.js (incl. that an out-of-set labeller's deny is ignored).
• [PARTIAL 2026-08-11] Moderator-set as data. The primitive exists (createAuthorityState({ root, actors }) + capability-gated reduceAdminState), and the headless example demonstrates resolving the honored set as data and ignoring an unauthorized labeller. Still open as a first-class helper: resolving that actor map from a signed, root-controlled kind-30000 set at runtime (with delegation) rather than the app assembling the actors object itself. Left as a focused follow-up.
• [DONE 2026-08-11] Allowlist / whitelist mode. The engine already honored requireAllowlist + allowlistMiss (evaluator.js), and the commerce example configured a seller allowlist by hand — but there was no reusable named preset. Shipped ALLOWLIST_POLICY (registry name allowlist): only publishers with a user-allow contribution are shown, every unlisted one is hidden across all four dimensions, administrative denials still apply on top, and protected actors (root/mods) are never gated. Symmetric to the denylist — populate userAllow the same way (signed contributions / NIP-32 allow labels). Covered by presets.test.js (unlisted hidden, allowlisted shown, protected bypasses); surfaced in the README preset list.

Medium

• [DONE 2026-08-11] Ship a standalone ESM single-file. Shipped @bitgate/standalone (packages/standalone/, npm run build:standalone → dist/bitgate.js, ~44 KB): the headless engine (core) + the Nostr codecs (nostr, incl. the kind-1985 label round-trip) esbuilt into one self-contained, dependency-free ESM file — @bitgate/verify's @noble deps are deliberately not pulled in. A no-build static site vendors the single file and gets the whole headless path. Verified dependency-free (no bare imports in the output) and end-to-end (a smoke test composes a decision from the entry). Documented in the README Packages table and the headless section; wired into npm run build.
• A worked example of BitGate feeding a feed ranking (the ranking dimension → a score multiplier) would have saved us reinventing it in the feed recipe.