diff --git a/docs/TODO.md b/docs/TODO.md new file mode 100644 index 0000000..d6db3c5 --- /dev/null +++ b/docs/TODO.md @@ -0,0 +1,178 @@ +# 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.