|
| 1 | +# Builderlab native companion |
| 2 | + |
| 3 | +The `block.builderlab` Settings plugin owns the UI; this optional Tauri plugin |
| 4 | +owns the session. The app includes it only with `--features builderlab`, paired |
| 5 | +with `BUZZ_BUILD_BUILDERLAB=1` for the frontend. See |
| 6 | +[configuration](../../docs/configuration.md#builderlab-session-shared-with-the-bl-cli). |
| 7 | + |
| 8 | +## Ownership and protocol |
| 9 | + |
| 10 | +- `auth`, `login`, `cancel`, and `sign_out` return only account metadata or fixed |
| 11 | + errors over `plugin:builderlab|…`. The local main webview is the only recipient |
| 12 | + of the plugin's capability. No generic OAuth, credential or authenticated-fetch |
| 13 | + API is exposed. |
| 14 | +- Storage is the source of truth. Each operation opens the `builderlab-auth` |
| 15 | + store under the resolved `bl` profile/service key. A mutex serializes this |
| 16 | + process's read/replace/compare-and-delete operations. Writes commit or roll |
| 17 | + back under that same lock; the state lock never spans a Keychain prompt. |
| 18 | +- A second login supersedes the first. Cancel/sign-out fence pending writes. |
| 19 | + Once an exchange starts, its spawned finish task survives a lost IPC caller: |
| 20 | + it either persists a verified session or attempts to revoke it. Both displaced |
| 21 | + and canceled minted sessions are revoked. Revocation has a five-second cap; |
| 22 | + server/network failures cannot guarantee remote revocation, and local sign-out |
| 23 | + still proceeds. A rotation observed before local delete is preserved. |
| 24 | +- The private callback receiver adapts Jarrod Sibbison's |
| 25 | + [PR #581](https://github.com/block/buzz-app/pull/581) at `5d84bb9174515aa8a50c5a0075c538633c7024c9`: |
| 26 | + loopback-only bind, random single-use path, exact Host, no Origin, GET only, |
| 27 | + 8 KiB request cap, 4 KiB code cap, five-second connection deadline and ten-minute |
| 28 | + attempt deadline. Malformed callbacks do not consume the attempt. The response |
| 29 | + uses CSP, no-store and no-referrer, and says the code was received, not that |
| 30 | + verification succeeded. The socket closes before publishing the result. |
| 31 | +- kgoose's CLI protocol accepts `{code}` and echoes `returnTo`. It does not offer |
| 32 | + client-bound PKCE or echo OAuth state; those require a server protocol change. |
| 33 | + This is not a general OAuth receiver. |
| 34 | +- Exchange credentials must be bounded printable ASCII; `/me` must have a |
| 35 | + nonblank subject. Redirects are disabled, bodies bounded, and only 401/403 |
| 36 | + invalidate saved sessions. Transport, truncated/stalled-body, malformed-body |
| 37 | + and 5xx failures preserve the shared item. HTTPS is required except for local |
| 38 | + development loopback endpoints. |
| 39 | +- Owned credentials and response buffers use `Zeroizing`; plain credentials |
| 40 | + returned/required by the CLI crate are wiped after use. HTTP, serde, OS and |
| 41 | + storage internals may retain copies. No credential is delivered to JavaScript |
| 42 | + or interpolated into an error. |
| 43 | + |
| 44 | +`builderlab-auth` supplies no transaction shared with other processes. Simultaneous |
| 45 | +`bl`/Buzz writes, including whole-file updates across profiles, remain a limitation. |
| 46 | +No app-owned credential cache, migration, retry loop or provider registry is added. |
| 47 | +Native identity binding and community management remain outside this plugin. |
| 48 | + |
| 49 | +## Validation |
| 50 | + |
| 51 | +```sh |
| 52 | +CARGO_TARGET_DIR=target bin/cargo test -p tauri-plugin-builderlab --locked |
| 53 | +CARGO_TARGET_DIR=target bin/cargo test -p buzz-foundation --features builderlab --lib browser_permissions_tests --locked |
| 54 | +CARGO_TARGET_DIR=target bin/cargo test -p buzz-foundation --lib browser_permissions_tests --locked |
| 55 | +CARGO_TARGET_DIR=target bin/cargo test -p buzzodz-plugins --features builderlab --locked |
| 56 | +bin/pnpm exec vitest run src/bundled/builderlab src/bundled/hosted-communities |
| 57 | +``` |
| 58 | + |
| 59 | +The native suite uses a fake HTTP service, real TCP callbacks, the CLI's real |
| 60 | +file-store format and gated/failing storage handles. It never touches Keychain. |
| 61 | +The app ACL test uses a marker handler, without opening windows or resolving |
| 62 | +the real session. Frontend tests mount React and exercise the real adapter with |
| 63 | +controlled IPC responses. No browser journeys are added or removed: the changed |
| 64 | +contract is plugin registration and account lifecycle, not browser geometry. |
| 65 | +Existing broker tests remain; shared-session wording moved to the new card. |
| 66 | +Tests for the removed unused `/v1/buzz/*` helper were removed with that API. |
| 67 | + |
| 68 | +Attended macOS Keychain/`bl` interoperability and Windows/Linux file-store runs |
| 69 | +remain required before native live-use acceptance. Independent review and human |
| 70 | +testing are separate from these automated checks. |
0 commit comments