ARC Polish

.codacy.yml

@@ -13,6 +13,8 @@ engines:
       - "functions/cliDocumentExchange.js"
       - "functions/contractSidechainLocal.js"
       - "functions/fabricSetup.js"
+      - "functions/fabricHomeEnv.js"
+      - "functions/fabricWalletIdentity.js"
       - "types/environment.js"
   # Codacy Opengrep (Semgrep fork) may re-report the same path-construction patterns.
   opengrep:
@@ -22,6 +24,8 @@ engines:
       - "functions/cliDocumentExchange.js"
       - "functions/contractSidechainLocal.js"
       - "functions/fabricSetup.js"
+      - "functions/fabricHomeEnv.js"
+      - "functions/fabricWalletIdentity.js"
       - "types/environment.js"
   # Cppcheck still scanned src/ despite root exclude_paths; tool-specific paths are reliable for PR gates.
   cppcheck:

AGENTS.md

@@ -1,5 +1,5 @@
 # Fabric Agents
-See also [DEVELOPERS.md](DEVELOPERS.md) (repo layout, tests) and [docs/PRODUCTION.md](docs/PRODUCTION.md) (release gate).
+See also [DEVELOPERS.md](DEVELOPERS.md) (repo layout, tests), [docs/PRODUCTION.md](docs/PRODUCTION.md) (release gate), and [docs/TYPES_AND_SERVICES.md](docs/TYPES_AND_SERVICES.md) (suite `types/` + `services/` layering vs http / Hub / Passport / GoonCitizen).
 
 ## Release posture
 - **Target:** `0.1.0-RC1` reference client — not a production-hardened VM claim

AUDIT.md

@@ -13,7 +13,7 @@ audit report.
 | Peer misbehavior / scoring | Implemented (integrity, pin, session, contract ops, logical-register, nest cap, temp ban) — see [SECURITY.md](SECURITY.md) |
 | P2P_RELAY amplification | Mitigated: bit-identical outer forward + nest depth cap + relay-as-is pin; gossip hop remains advisory |
 | Chat mesh amplify | Mitigated: per-origin relay budget (`CHAT_MAX_RELAYS_*`) |
-| Oversize wire frames | Mitigated: drop before parse/crypto (`HEADER_SIZE + MAX_MESSAGE_SIZE`) |
+| Oversize / undersize wire frames | Mitigated: drop before parse/crypto (`< HEADER_SIZE` or `> HEADER_SIZE + MAX_MESSAGE_SIZE`); unparseable buffers drop without score/ban |
 | Inventory HTLC address spoof | Mitigated: rebuild+match (`validateInventoryHtlcOffer`); AMP signer binding when present |
 | Paid `/confirm` without L1 proof | Mitigated: fail-closed local verify or Hub `ConfirmInventoryHtlcPayment` (`cliDocumentExchange`) |
 | Key reveal from hash echo | Mitigated: `authorizeDocumentKeyReveal` requires `settlementId`/`txid`; `forceReveal` opt-in only; inbound reveal requires key preimage + claim-after-open |
@@ -46,9 +46,10 @@ audit report.
 14. **Outstanding ARC / Peer follow-ups** — coordinated `contractId` → `contractIdentifier` rename; eager `messageHex` laziness; regenerate `API.md` field docs for `SCHEMA_P2P_PEER_GOSSIP` / `tryParseMessageBody` / `resolveSpend` opts when next running `npm run make:api`. Journal / re-fold caps and blinded-execution `at` bind are landed (see ARC §8).
 15. ~~**Beacon/ARC `CONTRACT_PUBLISH` authority collector**~~ — `collectContractAuthorityPubkeys` walks nested `members.signers` / `spendPolicy.validators` (not only top-level arrays), so Beacon genesis no longer fail-opens first-claim to any AMP signer.
 16. ~~**Peering self-suppress trust**~~ — candidate host/port validation + default-port normalize on self-key refuse + NOISE self-check fail-closed; offer/announce enqueue suppresses only when `verifiedPubkey` (AMP signer) is our key. Advertised `obj.pubkey` is informational.
-17. **OP_RETURN hallmarks** — core short-format encode/verify (`functions/fabricHallmark`); Hub publish/scan is operator opt-in. Hallmarks are not a BIP; `npm run report:bip-compliance` last run **2026-08-13** (mean stack **2.47**, 37 BIPs, no grade movement vs 2026-08-12). Remaining: Hub mainnet hallmark policy gates; BIP suite gaps (49/69/85/322/48/370/352/388) in `reports/bip-compliance.md`.
+17. **OP_RETURN hallmarks** — core short-format encode/verify (`functions/fabricHallmark`); Hub publish/scan is operator opt-in. Hallmarks are not a BIP; `npm run report:bip-compliance` last run **2026-08-15** (mean stack **2.62**, 37 BIPs; core Full **9**, Absent **5**; Hub Strong **12**, Absent **7**). Remaining: Hub mainnet hallmark policy gates; core Absent is **77 / 370 / 352 / 322 / 388**. Hub BIP-69 is Strong (unsigned PSBTs). See `reports/bip-compliance.md`.
 18. ~~**Blinded-execution `at` bind**~~ — `decisionSigningMessage` v2 includes `at`; `recordProposalDecision` requires it and rejects timestamp swaps under a valid signature.
 19. ~~**GroupChangeProposal roster bind**~~ — `signingStringForGroupChangeProposal` v2 includes canonical `members` / `signers` so BIP340 votes cannot be reused on a colliding `id` with a swapped roster.
+20. **MuSig2 is n-of-n** — BIP-327 is implemented; t-of-n Bitcoin spends remain Taproot script-path (`CHECKSIGADD`). FROST / ChillDKG / ROAST are not in-tree. Interactive `P2P_MUSIG_*` sessions are directed TCP only (`Peer#startMusig2`, `functions/musig2Session`). **Default `synthesizeDefaultLadder` for n≥2 now uses a MuSig2 internal key** (new address vs historical NUMS). Pass `internalKeyMode: 'nums'` to keep the old script-path-only address. Existing UTXOs at a NUMS vault stay there; they are not migrated by a policy rebuild.
 
 ### PR #183 review triage (feature/rsi)
 

CHANGELOG.md

@@ -1,7 +1,22 @@
 # `@fabric/core` Changelog
 Recent changes to Fabric Core.
 
+## 2026-08-15
+- **Fabric Message collections:** `functions/fabricMessageCollection` stores ordered AMP frames (`Message.toBuffer()` hex) as the canonical share format for contract journals, Discord / `GroupDataShare` packs, and peer replay. Dedupes by body hash, drops body-hash mismatches, JSON/JSONL save+restore, `replay` / `replayFold`. CLI: `npm run messages` (`scripts/replay-messages.js`). Docs: `docs/MESSAGE_COLLECTION.md`. Not a replacement for Hub `messages/*.json` activity logs.
+
+- **BIP-327 MuSig2:** first-party `functions/musig2` locked to the official BIP vectors (`tests/vectors/bip327/`). n-of-n Schnorr only — not a t-of-n replacement. **Default** `synthesizeDefaultLadder` / federation vault for **n≥2** uses the MuSig2 aggregate as the Taproot internal key (cooperative key-path; **new address** vs historical NUMS). k-of-n `OP_CHECKSIGADD` and CSV soft-tier stay script-path. Pass `internalKeyMode: 'nums'` to keep the NUMS-only address. Control blocks / PSBTs use the real internal key. Off-chain Beacon / GroupChange stay independent BIP-340 counts. **`P2P_MUSIG_*` is dispatched** on directed TCP (`functions/musig2Session` + `Peer#startMusig2`): START → ACCEPT / RECEIVE_COUNTER → SEND_PROPOSAL → REPLY → ACCEPT_PROPOSAL. Peel / foreign `P2P_RELAY` and generic carriers are ignored; AMP signer must be a listed participant; aggnonce is recomputed locally.
+
 ## 2026-08-14
+- **BIP helpers (compliance low-hanging fruit):** first-party `functions/bip69` (vin/vout lexicographic sort, official examples; singleton prevouts are validated), `functions/bip85` (HMAC entropy + BIP-39/WIF/XPRV/HEX vectors), `functions/bip21` (bitcoin: encode/parse; inventory HTLC funding hints), `functions/bip67` (`sortPubkeysBip67`; Taproot k-of-n, ARC spend keys, Beacon validators), `functions/bip125` (opt-in RBF nSequence helpers; HTLC refunds stay locktime-only MAX-1). Named BIP-48/49/84/86 path templates in `constants.js`; **default funds path remains BIP-44** `m/44'/0'/0'/0/0`. Bitcoin `_buildPSBT` applies BIP-69 before `addInput` / `addOutput`.
+- **Peer generic dispatch:** JSON `type: 98` (AMP `P2P_PEERING_OFFER`) is coerced via `Message.canonicalTypeName` and dispatched instead of `Unhandled Generic Message: 98`. Unhandled defaults no longer `JSON.stringify` the full body. `_registerActor` / `_registerContract` debug lines are names-only and gated on `settings.debug`. `_connect` derived-key summary reads `Key.pubkey` (`settings.public` is unset after `derive({ xprv })`, which logged `(no public key)` on the correct `m/44'/7778'/0'/0/0` path).
+- **Chat shoutbox:** Fabric TUI sends/receives first-class UTF-8 `P2P_CHAT_MESSAGE` (Peer `{ text }` + AMP signer, `P2P_PEER_ALIAS` nicknames). Shared helper `functions/fabricChatText`. Cap matches Peer `P2P_CHAT_MAX_CHARS` (2000).
+- **Peer/Service memory:** `Service.commit()` emits a compact `{ type, clock, id, patchCount }` and caps `history` (`SERVICE_COMMIT_HISTORY_MAX` / `commitHistoryMax`). It no longer wraps full `state` in an Actor (JSON.parse of Hub collections on every write). Peer isolates `settings.state` maps (no Hub `collections` alias), does not `commit()` on `_writeFabric` / `_registerActor` / every inbound frame, and drops ephemeral `host:port` actors on `_disconnect` / `_destroyFabric`. `Peer#beat` no longer snapshots full state.
+- **Operator home env:** `FABRIC_SEED` is the raw BIP32 seed **hex** (16–64 bytes); `FABRIC_MNEMONIC` is the BIP39 phrase; `FABRIC_XPRV` remains preferred. `Key` `FROM_SEED` accepts hex (legacy mnemonic in `seed` still works) and sets `status = 'seeded'`. `Environment` reads `FABRIC_MNEMONIC`. Helpers: `functions/fabricKeyMaterial`, `functions/fabricHomeEnv` (`~/.fabric/env` + `~/.fabric/hub-admin-token` Schnorr `OP_IDENTITY` admin Token), `functions/fabricWalletIdentity` (sealed `wallet.json` via `FABRIC_PASSWORD`). JSDoc on those helpers and `fabricChatText.chatActorIdOf` avoids TypeScript `?:`. `loadIdentityFromWalletFile` uses `loadWallet({ fromFile: true })` so leftover `FABRIC_SEED` cannot replace `wallet.json`. Semgrep/Opengrep exclude those home-env path helpers (Codacy ignores `nosemgrep`). Chaos fuzz prefers a live connection, lands signed frames before hostile AMP, and fails the playnet storm on unexpected peer errors. `node scripts/ensure-home-env.js` writes those files without printing secrets.
+- **RC1 first-tier contract:** `tests/rc1.first-tier.contract.js` locks the four production-readiness green domains (wire integrity, gossip/peering bounds, scoring/bans, identity/wallets) at the hostile-mesh bar. Peer drops **undersize** (`< HEADER_SIZE`) and unparseable frames before parse — truncated NOISE chunks are not body-hash mismatches and do not hard-ban.
+- **IdentityCrossSign lift:** `functions/identityCrossSign.js`, `fabricIdentitySchnorr.js`, `identityCrossSignVerify.js` (+ `.d.ts`) are the canonical gossip strings and BIP340 helpers. HTTP site-login / device-link stay in `@fabric/http` and re-export these leaves. `signCrossSign` binds `localPubkey` to `fabricKey.pubkey` (raw HD `Key` and Passport `{ privateKeyHex, xpub }` round-trip). Canonical strings require compressed or x-only hex pubkeys (no `:` in fields); builders keep only a 64-hex nonce; `signCrossSign` rejects unknown `kind`. `fabricIdentityIdFromPubkeyHex` requires a compressed 66-hex public key. `.d.ts` files declare real arities / `ok` unions. `createdAt` is unsigned.
+- **Peer dial storms:** `_fillPeerSlots` waits `PEER_CANDIDATE_RETRY_MS` (60s) before redialing the same candidate; refused TCP no longer constructs NOISE (shared handshake EventEmitter was leaking listeners). Transient `ECONNREFUSED` is recognized from the error message when Node omits `error.code`. `_connect` skips in-flight `_outboundDialTargets` so overlapping `connectTo` / reconnect cannot open duplicate sockets before `connections[target]` is set. Dial keys are canonical `host:port` (IPv6 bracketed), so `pubkey@host:port` cannot open a second TCP/NOISE session beside `host:port`. Candidate retry timestamps are pruned on queue eviction / expiry and capped to `maxCandidates`; `candidateRetryMs` must be finite and `> 0`. `_disconnect` and inbound encrypt-end / banned-static paths tear down NOISE. Outbound `connect` setup is try/caught so a handshake throw cannot leave the dial target stuck.
+- **Wallet writes:** `_writeWalletDocument` uses a pid + random tmp suffix so concurrent writes in one process cannot clobber the same `.tmp`.
+- **Peer `contract:message`:** `messageHex` is a getter so hot paths that ignore the wire hex skip `toBuffer()`.
 - **Tests:** coverage for `--password=VALUE` (`functions/cliPasswordArgv`), GroupChange `signers.set` vote bind, wallet atomic write / touchWallet truncate, advertised vs verified peering suppress, Beacon persist-fail retain, `Environment.stop()` key wipe, and related lock/setup fail-closed paths.
 - **Codacy (PR #183):** timing-safe setup password confirm; setup TUI treats cancel as a non-string password (no `== null`); hallmark hex length uses a literal class (no `new RegExp`); tier `when` paths skip `__proto__`/`constructor`/`prototype`; BIP65 lock constants avoid 32-bit hex literals; Semgrep/Opengrep exclude path-hardened `fabricSetup` / `environment` (containment already tested).
 - **Shutdown / create:** `Environment.stop()` calls `lockWallet()` so seed/xprv/plaintext keys wipe even when the idle-lock handler was never installed; `touchWallet` creates a missing file with exclusive `wx` and does not truncate on `EEXIST`.

DEVELOPERS.md

@@ -34,10 +34,10 @@ Working from a **git checkout** (not the global package) is best when you are ch
 ## Repository layout
 | Path | Role |
 |------|------|
-| `types/` | ES6 **classes** — `Actor`, `Peer`, `Service`, `Store`, `Message`, etc. CommonJS (`require`) throughout. |
+| `types/` | ES6 **classes** — `Actor`, `Peer`, `Service`, `Store`, `Message`, etc. CommonJS (`require`) throughout. Cross-package homes: **[docs/TYPES_AND_SERVICES.md](docs/TYPES_AND_SERVICES.md)**. |
 | `services/` | Long-running **integrations** (Bitcoin RPC, Lightning stubs, ZMQ, …) built on `Service`. |
 | `contracts/` | Language snippets, traces, and tooling (e.g. type dependency graph). |
-| `scripts/` | CLI entrypoints, doc helpers (`list-jsdoc-type-files.js`, `remove-legacy-types.sh`). |
+| `scripts/` | CLI entrypoints, doc helpers (`list-jsdoc-type-files.js`, `remove-legacy-types.sh`). **`scripts/replay-messages.js`** collects / replays AMP `FabricMessageCollection` documents (`functions/fabricMessageCollection.js`). |
 | `tests/` | Mocha suites; run with `npm test`. |
 | `settings/` | Default and environment-specific config; `settings/deprecations.js` holds legacy aliases. |
 | `assets/` | **Generated** browser bundles; rebuild with `npm run build` after type changes. |

MESSAGES.md

@@ -79,6 +79,12 @@ Primary sources:
 | `P2P_PEERING_OFFER` | 98 | `0x0062` | First-class peering-capacity offer. Relayed bit-identical; candidate queue + hop/rate limits. |
 | `P2P_SESSION_OFFER` | 93 | `0x005d` | Initiates peer session handshake. |
 | `P2P_SESSION_OPEN` | 94 | `0x005e` | Accepts/completes peer session handshake. |
+| `P2P_MUSIG_START` | 16928 | `0x4220` | Directed BIP-327 session open: `sessionId` + `msg` + packed pubkeys + initiator `pubnonce`. |
+| `P2P_MUSIG_ACCEPT` | 16929 | `0x4221` | First co-signer `pubnonce` (n=2 complete after this). |
+| `P2P_MUSIG_RECEIVE_COUNTER` | 16930 | `0x4222` | Remaining signers’ `pubnonce` (n>2). |
+| `P2P_MUSIG_SEND_PROPOSAL` | 16931 | `0x4223` | Coordinator publishes recomputed `aggnonce` (must match local `nonceAgg`). |
+| `P2P_MUSIG_REPLY_TO_PROPOSAL` | 16932 | `0x4224` | 32-byte partial signature. |
+| `P2P_MUSIG_ACCEPT_PROPOSAL` | 16933 | `0x4225` | 64-byte aggregated BIP-340 signature. |
 | `CONTRACT_PUBLISH` | 95 | `0x005f` | Publishes a contract definition; registers it under a deterministic `Actor` id (the contract **namespace**). Emits `contract:publish` and relays. |
 | `CONTRACT_MESSAGE` | 96 | `0x0060` | Namespaced contract event. Body MUST carry `contract: <id>`; dispatch routes by that namespace (emits `contract:message`). State-patch `ops` apply only to locally registered contracts; unknown ids are app-consumed, not fatal. |
 | `P2P_IDENT_REQUEST` | 1 | `0x0001` | Requests identity material from counterparty. |

POLICY.md

@@ -141,6 +141,12 @@ Several application types use codes **outside** this range (see [`constants.js`]
 | — | 1024 | `JSON_PATCH` † | JSON patch operation | ✅ Yes |
 | — | 16000 | `JSON_CALL` † | JSON function call | ✅ Yes |
 | — | 15103 | `GENERIC_MESSAGE` † | Hub/browser transitional carrier | ✅ Yes |
+| `0x4220` | 16928 | `P2P_MUSIG_START` † | Directed BIP-327 session open | ❌ No |
+| `0x4221` | 16929 | `P2P_MUSIG_ACCEPT` † | Co-signer pubnonce | ❌ No |
+| `0x4222` | 16930 | `P2P_MUSIG_RECEIVE_COUNTER` † | Additional pubnonce (n>2) | ❌ No |
+| `0x4223` | 16931 | `P2P_MUSIG_SEND_PROPOSAL` † | Coordinator aggnonce | ❌ No |
+| `0x4224` | 16932 | `P2P_MUSIG_REPLY_TO_PROPOSAL` † | Partial signature | ❌ No |
+| `0x4225` | 16933 | `P2P_MUSIG_ACCEPT_PROPOSAL` † | Aggregated BIP-340 signature | ❌ No |
 | `0x81`-`0x8F` (legacy draft) | … | CHAT / ACCEPT / REJECT / PAYMENT_* | Not all registered in `constants.js` — see Remaining work | ⚠️ Varies |
 
 ### Bitcoin Integration Types

PRIVACY.md

@@ -37,9 +37,24 @@ against a global observer.
   participation in that mesh to the hub operator and often to other peers.
 - **Document catalog entries** — Inventory responses expose ids, hashes, and prices
   you choose to advertise.
+- **`sensitive: true` on AMP Message** — zeros the wire **payment** `preimage` field
+  only. It does **not** encrypt the body or suppress mesh flood. See
+  [`docs/MESSAGE_BODY.md`](docs/MESSAGE_BODY.md).
 - **Logs** — With `settings.debug`, Peer may emit public-key diagnostics. Private
   key material must never be logged (see `types/peer.js` NOISE path).
 
+## Remaining privacy work (for future agents)
+Track suite-wide residuals in downstream OUTSTANDING docs. Core-owned leftovers:
+
+1. Default mesh chat remains cleartext flood (`P2P_CHAT_MESSAGE` / `P2P_RELAY`) —
+   confidentiality requires app seals or `SendOnion` + onion chat seal.
+2. `P2P_PEERING_OFFER` still advertises dialable `host:port` when operators publish
+   offers — intentional discovery, not a bug; do not “fix” by hiding offers without
+   an alternate discovery story.
+3. Keep documenting that `sensitive` ≠ encrypted so callers do not over-claim.
+
+See also: [docs/OUTSTANDING.md](docs/OUTSTANDING.md), Hub/GoonCitizen privacy queues.
+
 ## Sealed documents
 
 Priced documents may use AES-GCM sealed delivery (`documentSealedExchange`):

PUBLIC_API.md

@@ -38,6 +38,12 @@ Password-sealed JSON and in-memory lock sessions (CLI / setup wallets):
 `@fabric/core/functions/sealedBlob`, `@fabric/core/functions/identityLock`
 (ambient stubs `functions/sealedBlob.d.ts` / `functions/identityLock.d.ts`).
 
+Protocol identity Schnorr + IdentityCrossSign (device-link gossip strings):
+`@fabric/core/functions/fabricIdentitySchnorr`,
+`@fabric/core/functions/identityCrossSign`,
+`@fabric/core/functions/identityCrossSignVerify`. HTTP site-login / device-link
+handlers stay in `@fabric/http` and re-export these leaves.
+
 ### Services
 
 `@fabric/core/services/bitcoin`, `@fabric/core/services/lightning` — optional RPC

README.md

@@ -93,7 +93,8 @@ Before tagging or publishing, use [`docs/PRODUCTION.md`](docs/PRODUCTION.md) (pr
 ## Available Commands
 - The **`fabric`** binary is the Node harness for the default Blessed TUI (`chat`); optional `fabric.node` accelerates a tiny crypto surface — see [docs/CLI-BINARY.md](docs/CLI-BINARY.md).
 - `npm run cli` runs `scripts/fabric.js` (same entry as `npm run chat`).
-- `npm run dev` serves a developer interface over localhost HTTP.
+- `npm run dev` serves a developer handbook over localhost HTTP (`_book`).
+- `npm run example:smoke` runs the curated Key / chat / onion demos; Pages landing is https://fabriclabs.github.io/fabric/
 - `npm run docs` creates a local HTTP server for browsing documentation.
 - `npm run examples` creates a local HTTP server for interacting with examples.
 - `npm start` launches the Fabric shell locally (same as `npm run chat`).