@macula-io/ts 0.13.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,343 @@
+# macula-ts
+
+[![CI](https://img.shields.io/github/actions/workflow/status/macula-io/macula-ts/ci.yml?branch=main&label=CI)](https://github.com/macula-io/macula-ts/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](#license)
+[![Node](https://img.shields.io/badge/node-24.18%2B-339933?logo=node.js)](https://nodejs.org)
+[![zero install scripts](https://img.shields.io/badge/install--scripts-zero-success.svg)](#packaging-genuinely-zero-install-time-scripts)
+[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-support-ea4aaa.svg?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/rgfaber)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/macula-ts-full-dark.svg">
+    <img src="assets/macula-ts-full-light.svg" alt="Macula" width="320">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>TypeScript SDK for the Macula mesh, via FFI over macula-go</strong>
+</p>
+
+---
+
+> **Status, 2026-09-04:** identity generation, a real transport +
+> CONNECT/HELLO handshake, unary RPC (both roles), DHT record
+> lookups/publication, pubsub, content transfer, UCAN minting/inspection
+> + UCAN-gated calling, and direct-dial (both roles) are all
+> **live-verified against the real production fleet**
+> (`station-de-frankfurt.macula.io`). Streaming RPC, streaming/content
+> direct-dial, cert-chain-authorized direct-dial, and provider-side UCAN
+> policy gating don't exist yet — see [What's explicitly not yet
+> implemented](#whats-explicitly-not-yet-implemented). Published to npm
+> as `@macula-io/ts` with zero install-time scripts — see
+> [Packaging](#packaging-genuinely-zero-install-time-scripts). Full
+> development history, including every bug found and fixed along the
+> way, lives in [CHANGELOG.md](CHANGELOG.md), not here.
+
+## What is this?
+
+A TypeScript SDK for the Macula mesh protocol — real QUIC-based mesh
+connectivity from Node.js: identity, sessions, unary RPC, pub/sub,
+content transfer, UCAN capability tokens, and direct-dial, all reaching
+the real production fleet today. Built as an FFI binding over
+[macula-go](https://github.com/macula-io/macula-go) rather than a native
+reimplementation — see below for why.
+
+## Why FFI over macula-go, not a native TypeScript reimplementation
+
+Macula's mesh protocol runs over raw QUIC with a custom ALPN string
+(`"macula"`, not `"h3"`) and its own length-prefixed, deterministic-CBOR
+frame format — not HTTP/3. Node.js has no mature first-party QUIC stack
+that's actually usable for this today:
+
+- `node:quic` (Node's own built-in, experimental module) **does** work at
+  the transport level — the QUIC+TLS 1.3 handshake with ALPN `"macula"`
+  completes and a bidirectional stream opens against the real production
+  stations. But it is absent from every currently-supportable official
+  Node binary — compile-time gated out of the Node 24 and 26 LTS lines —
+  and the one line that does ship it (Node 25.x) is already past its own
+  EOL and crashes the process about a second after a successful
+  handshake (a native assertion failure in `Endpoint::FindSession`). Not
+  viable to depend on today.
+- No actively-maintained pure-JS or WASM QUIC implementation currently
+  exposes a public client API with custom-ALPN support (the most promising
+  one found, [quico](https://github.com/colocohen/quico), documents custom
+  ALPN only on its low-level *server* API — its client convenience API is
+  HTTP/3-specific).
+
+macula-go, macula-rust, macula-dotnet, and macula-php have all already
+proven this protocol works and are actively maintained. Rather than
+reimplement QUIC + deterministic CBOR + Ed25519 framing a fifth time in a
+language with no mature QUIC story of its own, macula-ts reuses macula-go's
+already-proven implementation through FFI — the same tradeoff
+[macula-php](https://github.com/macula-io/macula-php) already made
+successfully (see its `cabi/` directory, which this package's own `cabi/`
+is structurally modeled on, including its handle-based memory-ownership
+convention).
+
+## Sibling SDKs
+
+| Repo | Approach |
+|---|---|
+| [macula](https://github.com/macula-io/macula) | The reference SDK (Erlang/OTP) |
+| [macula-go](https://github.com/macula-io/macula-go) | Go port — same protocol |
+| [macula-rust](https://github.com/macula-io/macula-rust) | Native reimplementation (quinn, pure Rust) |
+| [macula-dotnet](https://github.com/macula-io/macula-dotnet) | Native reimplementation (System.Net.Quic / msquic) |
+| [macula-php](https://github.com/macula-io/macula-php) | FFI binding over macula-go (this package's structural precedent) |
+| **macula-ts** | FFI binding over macula-go |
+| [macula-station](https://github.com/macula-io/macula-station) | The station: DHT, SWIM, routing, peering |
+| [macula-realm](https://github.com/macula-io/macula-realm) | Managed-realm identity + certificate authority |
+
+## Architecture
+
+```
+src/*.ts  --(node-gyp-build)-->  addon/binding.cc (N-API)  --(static link)-->  cabi/  --(cgo)-->  macula-go
+```
+
+`cabi/` is a Go module that imports `macula-go` and builds with
+`go build -buildmode=c-archive` into a C ABI static archive (`libmacula.a`
++ `libmacula.h`) — not a shared library. `addon/binding.cc` is a small,
+purpose-built [node-addon-api](https://github.com/nodejs/node-addon-api)
+N-API addon (not a generic FFI bridge) that links `libmacula.a` in
+statically, so the resulting `.node` file is self-contained: nothing to
+locate or `dlopen` at runtime, no separate shared library to ship
+alongside it. `src/binding.ts` loads that addon via
+[`node-gyp-build`](https://github.com/prebuild/node-gyp-build) (a
+zero-dependency runtime loader) and re-exports its typed functions;
+`src/identity.ts` (and everything built on top of it) is the actual
+public TypeScript API, never touching the addon directly.
+
+**Memory ownership**, copied from macula-php's `cabi/` rather than
+reinvented: every opaque Go value (an identity keypair, a session, or an
+inbound "pending call" awaiting a `serve()` handler's reply) crosses the
+boundary as a `uintptr_t` from `runtime/cgo.Handle`. Hold it, pass it
+back for every operation on that value, and free it exactly once
+(`Identity#dispose()` on the TS side; a pending-call handle is freed
+automatically by whichever of `macula_pending_call_reply_result`/`_error`
+answers it). Fixed-length fields (a 32-byte NodeID or seed) are written
+directly into a caller-supplied output buffer. Every exported function
+resolves handles through a `recover()`-guarded lookup, never a raw
+`cgo.Handle(h)` — `cgo.Handle`'s own `.Value()`/`.Delete()` panic, not
+return an error, on a handle this process never issued or already freed.
+
+**RPC payloads cross this boundary as JSON text**, not another handle —
+`cabi/wirevalue.go` converts to/from macula-go's `cbor.Value`, ported from
+[macula-cli](https://github.com/macula-io/macula-cli)'s
+`internal/wirevalue` package (already proven against the same no-bool,
+bytes-as-hex-string rules) rather than reinvented. `Session.serve()`
+cannot hand a Go closure across the FFI boundary the way `ServeOneCall`
+expects, since the actual answer has to come from arbitrary, possibly-
+async TypeScript — so `cabi/serve.go` splits that one blocking Go call
+into three cgo exports instead (wait-for-call, read the pending call's
+procedure/payload, reply), the same split
+[macula-php](https://github.com/macula-io/macula-php)'s `cabi/serve.go`
+already proved for the identical problem.
+
+Development history (every bug found while building this, and how it was
+fixed) is in [CHANGELOG.md](CHANGELOG.md).
+
+## What's implemented
+
+- **Identity** — `Identity.generate()` (a fresh, S/Kademlia
+  puzzle-hardened Ed25519 identity), `Identity.fromSeedBytes()`
+  (deterministic reconstruction from a saved 32-byte seed),
+  `identity.nodeId`/`.privateSeedBytes`/`.dispose()`, and
+  `identity.sign(data)` — a generic Ed25519 primitive (no
+  application-specific message format baked in; `data` is signed exactly
+  as given). Using a disposed `Identity` throws instead of signing with a
+  freed handle.
+- **Session** — `Session.connect(host, port, identity)` dials a real
+  macula-station and completes the CONNECT/HELLO handshake (WebPKI
+  trust). `session.remoteAddr`, `session.stationNodeId` (the
+  HELLO-verified station identity), `session.close(identity, reason?)`
+  (idempotent). Using a session's accessors after `close()` throws
+  cleanly rather than crashing.
+- **RPC, caller role** — `session.call(procedure, payload, opts?)` sends
+  a signed CALL and waits for the matching RESULT/ERROR.
+  `payload`/the return value are `JsonValue` (string/number/null/array/
+  object — **no boolean**, since macula's wire CBOR has no bool type;
+  encode `true`/`false` as `1`/`0` yourself). A BOLT#4 ERROR frame (e.g.
+  `unknown_next_peer`) rejects with a `MaculaCallError` carrying the
+  numeric `code`, `bolt4Name`, `retryable`, and `detail`. `opts.realm` (a
+  64-character hex string) scopes the call to a realm other than the
+  all-zero default; `callWithUcan()`/`publish()`/`subscribe()` take the
+  identical option.
+- **RPC, provider role** — `session.serve(procedure, handler)` advertises
+  `procedure` and answers inbound CALLs against it forever, invoking
+  `handler(payload)` for each (sync or async). Resolves with an async
+  `stop()` that unadvertises and waits for the current poll tick to
+  finish. Only one `serve()` per `Session` at a time, and `call()`/
+  `serve()` refuse to run concurrently on the same `Session` — both read
+  frames off one shared control stream; open a second `Session` for the
+  other role.
+- **DHT** — `session.findRecordsByType(recordType)`,
+  `session.findRecords(key)`, `session.findRecord(key)`, and
+  `session.putProcedureAdvertisement(procedure, servingStation, opts?)`/
+  `session.putContentAnnouncement(mcid, endpoint, ttlMs?)` — typed
+  builders wrapping macula-go's own `dht.NewProcedureAdvertisement`/
+  `NewContentAnnouncement` (signed via `dht.Sign`, stored via
+  `dht.PutRecord`). There is deliberately no generic
+  `putRecord(type, arbitraryPayload)` — a procedure_advertisement/
+  content_announcement payload carries raw pubkey/MCID fields that must
+  be actual CBOR byte strings, which only the typed builders guarantee.
+- **Pubsub** — `session.publish(topic, payload, opts?)` (fire-and-forget,
+  no ack on the wire) and `session.subscribe(topic, handler, opts?)`.
+  `subscribe()` resolves with an async `stop()` that sends UNSUBSCRIBE
+  and does not resolve until the underlying reader goroutine has
+  genuinely exited. Only one `subscribe()` (and no active `serve()`) per
+  `Session` at a time — `publish()` itself is exempt, since it only ever
+  writes, so a `Session` can safely `publish()` on the same topic it's
+  `subscribe()`d to.
+- **Content transfer** — `session.putContent(data, name?)` /
+  `session.getContent(mcid)`, sent on their own dedicated QUIC stream
+  (not the shared control stream, so they run safely alongside an active
+  `serve()`/`subscribe()`). Data above 256 KiB is chunked and reassembled
+  automatically. `mcid` crosses the boundary as a lowercase hex string.
+  **This is a one-time TRANSFER mechanism, not durable object storage** —
+  a station may forget content after serving it, and there is no
+  list/delete operation.
+- **UCAN** — `Ucan.mint(issuer, audience, capabilities?, opts?)` (a
+  JWT-shaped, EdDSA-signed capability token, UCAN spec `"0.10.0"`) and
+  `Ucan.decode(token)` (parses claims WITHOUT verifying signature or
+  expiry — `Ucan#isExpired` mirrors macula-go's own semantics). Both are
+  pure local operations, no network I/O. `issuer`/`audience` DID strings
+  are `did:macula:<hex NodeID>`. `session.callWithUcan(procedure,
+  payload, ucanToken, opts?)` attaches a token to an outgoing CALL, for
+  invoking a procedure gated behind a provider-side `ucan.Policy.Required`
+  policy. **Deliberately places no restriction relating the calling
+  identity to the token's own `aud` claim** — macula's UCAN gate is a
+  BEARER-token check (verifies signature + expiry against the issuer
+  only, never the caller's identity against `aud`), so a client-side
+  "does my identity match this token's audience" guard would both reject
+  configurations the real wire-level gate accepts and misrepresent a
+  security property the mesh doesn't enforce. This SDK does **not**
+  expose `ucan.Verify` or `ucan.Policy` — only minting, inspecting, and
+  attaching a token are implemented; enforcing one is provider-side, out
+  of scope here.
+- **Direct-dial** — `session.resolveDirect(procedure, opts?)`,
+  `session.callDirect(procedure, payload, opts?)`,
+  `session.callDirectWithUcan(procedure, payload, ucanToken, opts?)`
+  (caller side) and `session.advertiseDirect(procedure, opts?)` plus a
+  standalone `keepAdvertisedDirect(session, procedure, opts?)` helper
+  (provider side). Resolves a signed `procedure_advertisement` DHT record
+  to its serving station's own signed `station_endpoint`, then dials that
+  station directly in one hop instead of depending on advertise-gossip
+  having reached whichever station the caller happens to already be
+  connected to. Trust is enforced at the application layer: the freshly
+  connected peer's HELLO-proven identity is checked against the exact
+  pubkey the signed DHT chain resolved. `advertiseDirect()` issues both a
+  plain ADVERTISE and the signed DHT record on the same call — both are
+  required for `resolveDirect()`+`callDirect()` to actually reach a live
+  route. `resolveDirect`/`callDirect`/`callDirectWithUcan`/
+  `advertiseDirect` share the same same-Session exclusivity guard as
+  `call()`/the DHT methods; a long-lived provider that also serves the
+  same procedure needs a separate `Session` (and identity — this fleet
+  enforces one connection per identity) to keep re-advertising on, which
+  is why `keepAdvertisedDirect()` is a standalone function rather than a
+  `Session` method.
+
+Every item above is live-verified against the real production fleet
+(`station-de-frankfurt.macula.io`), including negative/error paths and,
+where applicable, the actual packaged npm tarball rather than only the
+dev build — see [CHANGELOG.md](CHANGELOG.md) for the specific
+assertions, bugs found, and fixes for each.
+
+## What's explicitly not yet implemented
+
+Streaming RPC, streaming/content direct-dial (`OpenStreamDirect`,
+`PutDirect`/`GetDirect` — plain `Session.call`/`serve` direct-dial is
+implemented, see above), cert-chain-authorized direct-dial
+(`ResolveWithCertChain`/`CallWithCertChain`/`AdvertiseDirectWithCertChain`
+— opt-in even in macula-go itself), provider-side UCAN policy gating
+(`ucan.Policy`/`ServeOneCallGated` — this SDK can mint/attach a token but
+not enforce one on a served procedure), per-realm `serve`/`advertise`
+(these two still only ever use the all-zero realm — `call`/`callWithUcan`/
+`publish`/`subscribe`, and DHT's `putProcedureAdvertisement`, all DO now
+take an optional realm), a generic "put any DHT record type with an
+arbitrary payload" function (see above for why), a `station_endpoint`
+record builder (macula-go has none either — stations publish those
+themselves, not clients), and `Pinned`/`Insecure` trust modes (`WebPKI`
+only so far). Multiple concurrent `subscribe()` topics on one `Session`
+also isn't supported yet — one `subscribe()` (like one `serve()`) per
+`Session` at a time; open a second `Session` for a second topic. Each of
+these is a separate, later slice of work built on top of a working
+`Session`.
+
+## Testing
+
+```bash
+npx vitest run    # default suite, no network
+npm run test:live # MACULA_TS_LIVE=1 vitest run src/session.live.test.ts src/rpc.live.test.ts src/dht.live.test.ts src/pubsub.live.test.ts src/content.live.test.ts src/ucan.live.test.ts src/directdial.live.test.ts
+```
+
+`src/session.live.test.ts`, `src/rpc.live.test.ts`, `src/dht.live.test.ts`,
+`src/pubsub.live.test.ts`, `src/content.live.test.ts`,
+`src/ucan.live.test.ts`, and `src/directdial.live.test.ts` hit the real
+production fleet and are **not** part of default `npm test`/CI — opt in
+explicitly, gated behind `MACULA_TS_LIVE`. Same convention as macula-go's
+`live` build tag, macula-rust's `#[ignore]`, and macula-dotnet's
+`[Trait("Category","Live")]`: real-network tests are written and
+runnable, just excluded from the default/CI run so a station outage doesn't
+make ordinary CI flaky. `.github/workflows/ci.yml` exposes this as a
+manually-triggered (`workflow_dispatch`) job, never run automatically on
+push/PR.
+
+## Packaging: genuinely zero install-time scripts
+
+An earlier version of this package used [koffi](https://koffi.dev) (a
+generic dynamic FFI bridge) to load `libmacula.so` at runtime. That was
+replaced — koffi has its own native `install` script and ships no
+prebuilt binaries in its npm tarball, so it inherited the exact class of
+npm-install-script friction that
+[macula-mcp's better-sqlite3 dependency caused](https://github.com/macula-io/macula-mcp/blob/main/CHANGELOG.md)
+before that project moved to `node:sqlite`. No actively-maintained
+generic Node FFI library was found that avoids this.
+
+Instead, `addon/binding.cc` is a small addon purpose-built for exactly
+macula-ts's own exported functions (not a generic bridge), packaged with
+[`prebuildify`](https://github.com/prebuild/prebuildify) +
+[`node-gyp-build`](https://github.com/prebuild/node-gyp-build) — the same
+pattern used by `sharp`, `bcrypt`, and other native modules that need zero
+consumer-side compilation. The compiled `.node` binary for each supported
+platform is baked into `prebuilds/` and published as part of the npm
+package itself (**not** gitignored — there is nothing to build or fetch
+at a consumer's `npm install` time). `package.json` has no `install`,
+`postinstall`, or `preinstall` script at all.
+
+Five platforms are covered: `linux-x64`, `linux-arm64`, `darwin-arm64`,
+`darwin-x64`, and `win32-x64`. `.github/workflows/prebuilds.yml` builds
+each on a real GitHub-hosted runner for that platform (`CGO_ENABLED=1`
+needs a matching native C toolchain per target, so cross-compiling
+`cabi/`'s Go archive from Linux isn't the right approach here — the same
+reason `sharp`/`bcrypt`/etc. use real per-OS runners) and commits the
+results back to `main`. `.github/workflows/ci.yml`'s "Confirm the
+committed prebuild is not stale" step re-verifies, on every push, that
+`linux-x64`'s committed binary still matches a fresh rebuild of current
+source, byte for byte. Getting that check — and the Windows build — to
+actually hold surfaced three real build-toolchain bugs; see
+[CHANGELOG.md](CHANGELOG.md) for the specifics.
+
+## Development
+
+```bash
+npm run build:go   # builds cabi/build/libmacula.a -- must run BEFORE
+                    # npm install, since binding.gyp's mere presence in
+                    # this repo (not in the published package) makes npm
+                    # implicitly run `node-gyp rebuild` as part of
+                    # install, and that rebuild links against this archive
+npm install         # builds the native addon (via the implicit node-gyp
+                    # rebuild above) and installs JS deps
+npm run typecheck
+npm test
+npm run build:prebuilds   # regenerate prebuilds/ after touching addon/ or cabi/ -- commit the result
+npm run build             # local dev build: addon + tsc
+```
+
+Requires Go >=1.27 (for `cabi/`), a C++ toolchain (for `addon/`), and Node
+>=24.18.1 (see `engines` in `package.json` — matches the same floor
+macula-mcp landed on for `node:sqlite`; earlier Node lines don't ship it).
+None of this is required to *consume* the published package — only to
+work on macula-ts itself.
+
+## License
+
+Apache-2.0

package/dist/binding.d.ts

@@ -0,0 +1,47 @@
+export type Handle = number | bigint;
+export declare const native: {
+    identityGenerate(): bigint;
+    identityFromSeedBytes(seed32: Uint8Array): bigint;
+    identityNodeId(handle: Handle): Uint8Array;
+    identityPrivateBytes(handle: Handle): Uint8Array;
+    identityFree(handle: Handle): void;
+    identitySign(handle: Handle, data: Uint8Array): Uint8Array;
+    sessionConnect(host: string, port: number, identityHandle: Handle): Promise<bigint>;
+    sessionRemoteAddr(handle: Handle): string;
+    sessionStationNodeId(handle: Handle): Uint8Array;
+    sessionClose(handle: Handle, identityHandle: Handle, reason: string): Promise<void>;
+    sessionCall(sessionHandle: Handle, identityHandle: Handle, procedure: string, realm: Uint8Array | undefined, payloadJson: string, timeoutMs: number): Promise<string>;
+    ucanMint(identityHandle: Handle, issuer: string, audience: string, capabilitiesJson: string, expiresAt: number | undefined, notBefore: number | undefined, nonce: string, factsJson: string | undefined, proofsJson: string | undefined): string;
+    ucanDecode(token: string): string;
+    sessionCallWithUcan(sessionHandle: Handle, identityHandle: Handle, procedure: string, realm: Uint8Array | undefined, payloadJson: string, timeoutMs: number, ucanToken: string): Promise<string>;
+    sessionAdvertise(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, procedure: string): Promise<void>;
+    sessionUnadvertise(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, procedure: string): Promise<void>;
+    serveWaitForCall(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, procedure: string, timeoutMs: number): Promise<Handle | null>;
+    pendingCallProcedure(pendingHandle: Handle): string;
+    pendingCallPayloadJson(pendingHandle: Handle): string;
+    pendingCallReplyResult(pendingHandle: Handle, resultJson: string): Promise<void>;
+    pendingCallReplyError(pendingHandle: Handle, detail: string): Promise<void>;
+    dhtFindRecordsByType(sessionHandle: Handle, identityHandle: Handle, recordType: number): Promise<string>;
+    dhtFindRecords(sessionHandle: Handle, identityHandle: Handle, key32: Uint8Array): Promise<string>;
+    dhtFindRecord(sessionHandle: Handle, identityHandle: Handle, key32: Uint8Array): Promise<string | null>;
+    dhtPutProcedureAdvertisement(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, procedure: string, servingStation32: Uint8Array, ttlMs: number): Promise<string>;
+    dhtPutContentAnnouncement(sessionHandle: Handle, identityHandle: Handle, mcid34: Uint8Array, endpoint: string, ttlMs: number): Promise<string>;
+    sessionPublish(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, topic: string, payloadJson: string, ttlMs: number): Promise<void>;
+    sessionSubscribeStart(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, topic: string, onEvent: (msg: {
+        kind: "event";
+        topic: string;
+        publisher: Uint8Array;
+        seq: number;
+        payloadJson: string;
+    } | {
+        kind: "closed";
+        error: string;
+    }) => void): Promise<bigint>;
+    sessionSubscribeStop(subscriptionHandle: Handle): Promise<void>;
+    contentPut(sessionHandle: Handle, identityHandle: Handle, data: Uint8Array, name: string): Promise<string>;
+    contentGet(sessionHandle: Handle, identityHandle: Handle, mcidHex: string): Promise<Uint8Array | null>;
+    directdialResolve(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, procedure: string): Promise<string>;
+    directdialCall(sessionHandle: Handle, identityHandle: Handle, procedure: string, realm: Uint8Array | undefined, payloadJson: string, timeoutMs: number): Promise<string>;
+    directdialCallWithUcan(sessionHandle: Handle, identityHandle: Handle, procedure: string, realm: Uint8Array | undefined, payloadJson: string, timeoutMs: number, ucanToken: string): Promise<string>;
+    directdialAdvertise(sessionHandle: Handle, identityHandle: Handle, realm: Uint8Array | undefined, procedure: string, ttlMs: number): Promise<void>;
+};