Skip to content

Commit 51df533

Browse files
wesbillmanCarl
andauthored
docs: define shared host boundaries and Canvas contract cases (#658)
Signed-off-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz> Co-authored-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz>
1 parent 97155e7 commit 51df533

8 files changed

Lines changed: 280 additions & 86 deletions

File tree

‎AGENTS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ callers, and relevant design docs; preserve documented product decisions and
4141
ownership boundaries. Resolve answerable questions from evidence; ask before
4242
deviating from agreed scope or product behavior.
4343

44+
For cross-host changes, follow [shared logic and host boundaries](docs/contributing.md#shared-logic-and-host-boundaries).
45+
Name the existing feature owner/current callers, preserved behavior or approved
46+
host differences, and which host the validation actually exercises. Keep shared
47+
contracts executable in the existing tests; frontend checks do not replace host
48+
signing or IPC enforcement.
49+
4450
Agent selection must consume `session.agentChoices`, not independently reconstruct
4551
native/legacy inventories. Keep usable partial choices distinct from complete
4652
inference evidence; preserve each action's membership/archive policy. See

‎README.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,9 @@ just desktop --port 1431
4040

4141
Ports do not isolate account credentials or native plugin data. For separate
4242
plugin profiles, use the existing `BUZZODZ_PROFILE` setting described below.
43-
Without live opt-in they run the shell without relay identity access.
43+
Without a public viewer pin, browser development runs the shell/fixtures;
44+
supported desktop development can use [native identity and relay access](docs/identity.md).
45+
See the [host-mode matrix](docs/contributing.md#shared-logic-and-host-boundaries).
4446
`just iterate` applies formatting and runs fast checks plus the frontend build.
4547
`just scan` adds tests and native checks. [PR CI](.github/workflows/ci.yml) runs
4648
those checks in cached, parallel jobs with sharded browser journeys.
@@ -70,13 +72,15 @@ per-platform steps and limits.
7072

7173
## Relay channels
7274

73-
Live development currently requires **an existing Buzz account in the OS credential
74-
store**: the `buzz-desktop` / `secrets` Keychain entry on macOS, or the same entry in
75+
Live **browser/broker development** requires an existing Buzz account in the OS credential
76+
store: the `buzz-desktop` / `secrets` Keychain entry on macOS, or the same entry in
7577
the freedesktop secret service on Linux (read with libsecret's `secret-tool`, so
7678
install `libsecret-tools` and run inside an unlocked desktop session). This development broker is not native
7779
sign-in and is not included in packaged builds. `just web` and `just desktop` run
78-
it automatically once `BUZZ_DEV_VIEWER` is configured; without that pin they start
79-
in the non-live shell/fixture state.
80+
it automatically once `BUZZ_DEV_VIEWER` is configured, including inside the native
81+
window. Without that pin, web stays in shell/fixture mode and supported desktop
82+
uses its separate [native identity path](docs/identity.md). Removing the pin can
83+
change the active identity; it does not migrate the legacy key.
8084

8185
1. Copy your existing Buzz account's **public key** (npub or 64-character hex).
8286
2. Add it to the git-ignored `.env.local` at this repository's root. The optional

‎dev/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Browser development host
2+
3+
This directory contains the Node host used by live browser development and
4+
broker-backed tests, plus development tooling. It is checked-in source, not a
5+
cache or another relay server. Packaged desktop uses the native Rust host.
6+
7+
See [shared logic and host boundaries](../docs/contributing.md#shared-logic-and-host-boundaries)
8+
for the runtime/identity matrix, ownership rules and cross-host test expectations.
9+
Keep platform-neutral feature policy under its existing `src/features/*` owner;
10+
retain host custody and boundary enforcement here. Existing tests are discovered
11+
by Vitest. [Broker setup](../README.md#relay-channels) requires an explicit public
12+
identity pin; never put a private key in environment configuration.

‎dev/channel-kit.test.mjs‎

Lines changed: 11 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { expect, it } from "vitest";
2+
import canvasCases from "../src/features/channel-templates/canvas-signing-contract.json";
23
import { keypair, signed } from "../src/features/relay/testing.ts";
34
import {
45
coordinate,
@@ -141,37 +142,18 @@ it("expands multiple teams and individual agents by exact key without namesake c
141142
);
142143
});
143144

144-
it("admits only bounded Canvas writes with one exact channel and no notification or privilege tags", () => {
145+
// Shape only: the broker additionally checks freshness; Rust also deserializes
146+
// EventTemplate and bounds the signed serialization. See contributing.md.
147+
it.each(canvasCases)("Canvas signing shape: $name", ({ accepted, tags }) => {
148+
expect(validCanvas({ kind: 40100, content: "# Plan", tags })).toBe(accepted);
149+
});
150+
151+
it("bounds Canvas content in UTF-8 bytes, not JavaScript characters", () => {
145152
const canvas = {
146153
kind: 40100,
147-
content: "# Plan",
148154
tags: [["h", "11111111-1111-4111-8111-111111111111"]],
149155
};
150-
expect(validCanvas(canvas)).toBe(true);
151-
for (const revision of ["none", "a".repeat(64)])
152-
expect(
153-
validCanvas({
154-
...canvas,
155-
tags: [...canvas.tags, ["expected-revision", revision]],
156-
}),
157-
).toBe(true);
158-
for (const tags of [
159-
[...canvas.tags, ["expected-revision", "bad"]],
160-
[...canvas.tags, ["expected-revision", "A".repeat(64)]],
161-
[...canvas.tags, ["expected-revision", "none", "extra"]],
162-
[
163-
...canvas.tags,
164-
["expected-revision", "none"],
165-
["expected-revision", "none"],
166-
],
167-
[...canvas.tags, null],
168-
[],
169-
[...canvas.tags, ...canvas.tags],
170-
[...canvas.tags, ["p", owner.pubkey]],
171-
[["h", "invalid"]],
172-
])
173-
expect(validCanvas({ ...canvas, tags })).toBe(false);
174-
expect(validCanvas({ ...canvas, content: "é".repeat(13 * 1024) })).toBe(
175-
false,
176-
);
156+
const content = "é".repeat(12 * 1024);
157+
expect(validCanvas({ ...canvas, content })).toBe(true);
158+
expect(validCanvas({ ...canvas, content: `${content}x` })).toBe(false);
177159
});

‎docs/contributing.md‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -157,9 +157,11 @@ ports must be integers from 1 to 65535. Browser dev
157157
prints its selected URL and can use a later port when the requested port is
158158
occupied. Port selection does not isolate credentials or native plugin data;
159159
use the existing `BUZZODZ_PROFILE` setting for separate plugin profiles.
160-
Both run the development broker with your identity when the public
161-
`BUZZ_DEV_VIEWER` pin is configured in `.env.local`, and start without live
162-
identity otherwise; see [the setup and Keychain requirements](../README.md#relay-channels).
160+
A public `BUZZ_DEV_VIEWER` pin enables the legacy development broker for either
161+
command. Without it, browser development has no live broker identity, while
162+
supported desktop development can use native identity and relay access. See
163+
[host modes below](#shared-logic-and-host-boundaries) and
164+
[the broker setup requirements](../README.md#relay-channels).
163165

164166
After creating a worktree, bootstrap it from the checkout whose local development
165167
configuration it should inherit:
@@ -194,6 +196,70 @@ Ordinary checkouts, non-macOS launches, and `pnpm tauri build` keep their existi
194196
icons. This does not change the app identifier, credentials, profiles, or
195197
notification settings.
196198

199+
## Shared logic and host boundaries
200+
201+
Browser and desktop share the React application, community sessions, durable
202+
outbox, protocol models and live scheduler. `dev/` is the Node host for browser
203+
development and broker-backed tests, not generated output or another relay.
204+
Packaged desktop uses the Rust host. Node code does not run in a browser merely
205+
because it serves one, and packaged desktop does not need a Node backend.
206+
207+
| Mode | Identity and relay host |
208+
| --- | --- |
209+
| `just web`, public `BUZZ_DEV_VIEWER` pin | Node broker using the pinned existing legacy identity (macOS/Linux) |
210+
| `just web`, no pin | Shell/fixtures; no live broker identity |
211+
| `just desktop`, public pin | Legacy broker identity/relay access, even inside the native window; native-only capabilities may coexist |
212+
| `just desktop`, no pin | Native identity/relay access on supported macOS, Windows and Linux |
213+
| Packaged desktop | Native host; production builds exclude the dev broker regardless of the pin |
214+
215+
A static frontend build does not supply a standalone browser login/backend.
216+
The public pin does not migrate keys. Native debug worktrees share a credential
217+
namespace distinct from release and legacy broker credentials; ports and plugin
218+
profiles do not isolate those keys. Removing the pin may change the active
219+
identity, not just the transport. Do not change defaults, credentials or a running
220+
app as incidental cleanup. See [identity custody and acceptance](identity.md).
221+
222+
### Where behavior belongs
223+
224+
- Put platform-neutral models, edits and protocol policy in their existing
225+
`src/features/*` owner, with current callers rather than speculative adapter
226+
parity. The Node host and native frontend adapter can reuse dependency-free
227+
TypeScript where appropriate;
228+
[sidebar edits](../src/features/relay/sidebar-edits.ts) and
229+
[community commands](../src/features/communities/admin-protocol.ts) are examples.
230+
Shared modules must not depend on Node, Tauri or a dev-host implementation.
231+
- Keep signing keys, decryption, secure storage, subprocesses and host I/O in the
232+
host. Each independently callable HTTP/IPC boundary retains its own validation,
233+
signing policy, destination/identity binding, resource limits, cancellation and
234+
lifecycle ownership. Moving checks into shared frontend code is not a substitute
235+
for Rust enforcement. The relay remains the access-control authority.
236+
- For necessary cross-language implementations, share concrete contract cases
237+
rather than inventing a universal adapter or code generator. Existing JSON
238+
fixtures can be read by Vitest and Rust `include_str!`. Document intentional or
239+
unresolved differences with separate expected outcomes; neither implementation
240+
automatically defines the intended policy. Changing those outcomes is a behavior
241+
decision, not a refactor. Do not add a second source of feature policy in `dev/`.
242+
243+
### Review and evidence
244+
245+
A cross-host change names its feature owner/current consumers, supported modes,
246+
behavior preserved or explicitly approved differences, and the duplicate code it
247+
removes. Update the feature's contract cases and relevant wiring tests in the
248+
same change. Reuse existing runners and CI; this is not an extra full-suite gate
249+
for each edit. Keep feature details with their owner, not copied into this guide.
250+
251+
[Canvas shape cases](../src/features/channel-templates/canvas-signing-contract.json)
252+
are consumed by the Node and Rust tests. They cover kind-40100 tag shape, including
253+
an explicitly rejected native deserialization case; each host separately tests the
254+
UTF-8 content limit. This is not whole endpoint parity: broker freshness checks,
255+
native serialized-event limits, HTTP/IPC authorization and publication outcomes
256+
are separate layers. Existing host-specific checks remain necessary.
257+
258+
Report the exact snapshot and host/mode exercised. A broker-backed browser fixture,
259+
or a Tauri window using that broker, does not prove native signing, OS storage,
260+
networking or filesystem behavior. Native/live acceptance needs an agreed isolated
261+
identity/data setup; browser fixtures and test identities must never use real keys.
262+
197263
## Interactive product iteration
198264

199265
While shaping the first version, default to **edit → human tries the running app

‎docs/identity.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,10 @@ acquisition is not implemented, so deployments enforcing it are outside acceptan
118118
Windows/Linux custody, credential migration and release-signing acceptance remain
119119
separate limitations.
120120

121-
Development with `VITE_BUZZ_LIVE=1` continues to use its pinned legacy broker
122-
identity, and does not offer native private-key controls. Creating/importing the
121+
Development with a public `BUZZ_DEV_VIEWER` pin enables the legacy broker
122+
(Vite derives `VITE_BUZZ_LIVE=1`), even inside `just desktop`, and does not offer
123+
native private-key controls. Without the pin, supported desktop development uses
124+
the native identity path; see the [host-mode matrix](contributing.md#shared-logic-and-host-boundaries). Creating/importing the
123125
new native item does not update that old blob. Future reset/rotation would not
124126
synchronize copies automatically; neither operation is in this scope.
125127

‎src-tauri/src/relay/tests.rs‎

Lines changed: 38 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2081,56 +2081,47 @@ async fn preference_batches_reject_invalid_ciphertext_after_signature_verificati
20812081
}
20822082

20832083
#[test]
2084-
fn canvas_signing_bounds_revision_preconditions_and_allows_exact_legacy_retries() {
2085-
let channel = vec![
2086-
"h".to_string(),
2087-
"11111111-1111-4111-8111-111111111111".to_string(),
2088-
];
2089-
let event = |tags| EventTemplate {
2084+
fn canvas_signing_shape_matches_broker_contract() {
2085+
let cases: serde_json::Value = serde_json::from_str(include_str!(
2086+
"../../../src/features/channel-templates/canvas-signing-contract.json"
2087+
))
2088+
.unwrap();
2089+
for case in cases.as_array().unwrap() {
2090+
// Tag shape plus EventTemplate deserialization, not IPC wiring, broker
2091+
// freshness, the native signing budget or publication.
2092+
let event = serde_json::from_value::<EventTemplate>(serde_json::json!({
2093+
"kind": 40100, "created_at": 100, "content": "# Plan", "tags": case["tags"]
2094+
}));
2095+
let accepted = if case["deserializes"] == false {
2096+
assert!(event.is_err(), "{}", case["name"]);
2097+
false
2098+
} else {
2099+
let event = event.unwrap_or_else(|error| panic!("{}: {error}", case["name"]));
2100+
validate_event("https://relay.test", &event).is_ok()
2101+
};
2102+
assert_eq!(
2103+
accepted,
2104+
case["accepted"].as_bool().unwrap(),
2105+
"{}",
2106+
case["name"]
2107+
);
2108+
}
2109+
}
2110+
2111+
#[test]
2112+
fn canvas_content_is_bounded_in_utf8_bytes() {
2113+
let mut event = EventTemplate {
20902114
kind: 40100,
2091-
content: "# Plan".into(),
20922115
created_at: 100,
2093-
tags,
2116+
content: "é".repeat(12 * 1024),
2117+
tags: vec![vec![
2118+
"h".into(),
2119+
"11111111-1111-4111-8111-111111111111".into(),
2120+
]],
20942121
};
2095-
assert!(validate_event("https://relay.test", &event(vec![channel.clone()])).is_ok());
2096-
for revision in ["none".to_string(), "a".repeat(64)] {
2097-
assert!(validate_event(
2098-
"https://relay.test",
2099-
&event(vec![
2100-
channel.clone(),
2101-
vec!["expected-revision".into(), revision]
2102-
])
2103-
)
2104-
.is_ok());
2105-
}
2106-
for tags in [
2107-
vec![],
2108-
vec![channel.clone(), channel.clone()],
2109-
vec![channel.clone(), vec!["p".into(), "a".repeat(64)]],
2110-
vec![
2111-
channel.clone(),
2112-
vec!["expected-revision".into(), "bad".into()],
2113-
],
2114-
vec![
2115-
channel.clone(),
2116-
vec!["expected-revision".into(), "A".repeat(64)],
2117-
],
2118-
vec![
2119-
channel.clone(),
2120-
vec!["expected-revision".into(), "none".into(), "extra".into()],
2121-
],
2122-
vec![
2123-
channel.clone(),
2124-
vec!["expected-revision".into(), "none".into()],
2125-
vec!["expected-revision".into(), "none".into()],
2126-
],
2127-
vec![channel.clone(), vec![]],
2128-
] {
2129-
assert!(validate_event("https://relay.test", &event(tags)).is_err());
2130-
}
2131-
let mut too_large = event(vec![channel]);
2132-
too_large.content = "é".repeat(13 * 1024);
2133-
assert!(validate_event("https://relay.test", &too_large).is_err());
2122+
assert!(validate_event("https://relay.test", &event).is_ok());
2123+
event.content.push('x');
2124+
assert!(validate_event("https://relay.test", &event).is_err());
21342125
}
21352126

21362127
#[test]

0 commit comments

Comments
 (0)