zero-trust-application-channel 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +40 -39
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,68 +1,69 @@
|
|
|
1
1
|
# zero-trust-application-channel
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
(Fastify/PG/ContainerProxy) tüketici projede yaşar.
|
|
3
|
+
Generic, multiplexed WebSocket tunnel: HTTP/WS reverse-proxying and session
|
|
4
|
+
management over a single outbound connection. This package is the **core
|
|
5
|
+
library** — independent of any application or monorepo. Domain adapters
|
|
6
|
+
(Fastify/PG/container proxies) live in the consuming project.
|
|
8
7
|
|
|
9
|
-
|
|
10
|
-
**field→container**
|
|
11
|
-
|
|
12
|
-
(
|
|
8
|
+
**Two deployments, one package (v2):** the same generic package serves both
|
|
9
|
+
**field→container** and **field→boss** topologies — the register schema is
|
|
10
|
+
neutral (`peerId` + `peerType`), and session/cookie/allowlist behaviour is
|
|
11
|
+
injected via config (see [`../docs/CONTRACTS.md`](../docs/CONTRACTS.md)).
|
|
13
12
|
|
|
14
|
-
##
|
|
13
|
+
## Contents
|
|
15
14
|
|
|
16
|
-
|
|
|
15
|
+
| Module | Responsibility |
|
|
17
16
|
|---|---|
|
|
18
|
-
| `codec` | Binary frame codec — 9
|
|
19
|
-
| `protocol` |
|
|
20
|
-
| `connector` | `TunnelConnector` — outbound WS
|
|
21
|
-
| `channel` | `ISocketClient`/`WsSocketClient` (ws adapter), `ITunnelChannel` (client
|
|
22
|
-
| `client` | `TunnelClient` — stream
|
|
23
|
-
| `session` | `ClientSessionStore` + `ClientSessionServer` —
|
|
24
|
-
| `proxy` | `SessionGateway` + `HubSessionStore` + `TunnelProxy` — hub
|
|
25
|
-
| `logger` / `token` / `audit` / `snapshot` / `types` |
|
|
17
|
+
| `codec` | Binary frame codec — 9-byte header (streamId u32 BE + seq u32 BE + flags FIN/RST/WS_OP); `decode` never throws (`Result`) |
|
|
18
|
+
| `protocol` | Control message types + zod schemas (register/ack — v2 `peerId` + `peerType`, heartbeat, telemetry, stream-*, open-session/*); `TUNNEL_PROTOCOL_VERSION = 2` |
|
|
19
|
+
| `connector` | `TunnelConnector` — outbound WS client + state machine + exponential backoff (`ReconnectDelay`) |
|
|
20
|
+
| `channel` | `ISocketClient`/`WsSocketClient` (ws adapter), `ITunnelChannel` (client side), `IHubChannel` (hub side, carries peerId) |
|
|
21
|
+
| `client` | `TunnelClient` — stream multiplexing, credit-based backpressure, dual upstream routing, WS bridge |
|
|
22
|
+
| `session` | `ClientSessionStore` + `ClientSessionServer` — ephemeral session JWT (`ITokenSigner` injection) |
|
|
23
|
+
| `proxy` | `SessionGateway` + `HubSessionStore` + `TunnelProxy` — hub-side session + HTTP/WS proxy (`IHubChannel`/`IStreamSink`/`IAuditSink` injection; cookieName + PathAllowlist config) |
|
|
24
|
+
| `logger` / `token` / `audit` / `snapshot` / `types` | Independence contracts — minimal `ILogger`, `ITokenSigner`, `IAuditSink`, `ISnapshotSource`, generic `TunnelRole`/`TunnelUser`/`TunnelTelemetryPoint` |
|
|
26
25
|
|
|
27
|
-
##
|
|
26
|
+
## Dependencies
|
|
28
27
|
|
|
29
|
-
`ws
|
|
30
|
-
|
|
31
|
-
|
|
28
|
+
`ws` + `zod` — nothing else. (`jose` is an optional peer, used only by the
|
|
29
|
+
`./test-helpers` subpath; production code works through injected
|
|
30
|
+
`ITokenSigner`.)
|
|
32
31
|
|
|
33
|
-
##
|
|
32
|
+
## Example — loopback end-to-end (no application code)
|
|
34
33
|
|
|
35
34
|
```bash
|
|
36
35
|
bun lib/examples/loopback-demo.mjs
|
|
37
36
|
```
|
|
38
37
|
|
|
39
|
-
|
|
40
|
-
(client
|
|
41
|
-
|
|
38
|
+
In-package demo: `HubHarness` (hub side) ↔ `TunnelConnector` + `TunnelClient`
|
|
39
|
+
(client side) ↔ `SessionGateway` + `TunnelProxy` — register → session → tunnel
|
|
40
|
+
HTTP → WS bridge over a single real WS channel. The same flow runs as a test:
|
|
42
41
|
|
|
43
42
|
```bash
|
|
44
|
-
bun
|
|
43
|
+
bun run test # includes loopback.spec.ts
|
|
45
44
|
```
|
|
46
45
|
|
|
47
|
-
##
|
|
46
|
+
## Tests & quality gates
|
|
48
47
|
|
|
49
|
-
- `
|
|
50
|
-
- `
|
|
51
|
-
-
|
|
48
|
+
- `bun run test` — unit + spec + loopback end-to-end
|
|
49
|
+
- `bun run typecheck` — `tsc --noEmit` (production code, tests excluded)
|
|
50
|
+
- Security-critical modules (codec, connector, client, proxy) target ≥90%
|
|
51
|
+
branch coverage.
|
|
52
52
|
|
|
53
|
-
##
|
|
53
|
+
## Contract summary
|
|
54
54
|
|
|
55
55
|
```ts
|
|
56
|
-
// Client
|
|
56
|
+
// Client side: TunnelConnector already is an ITunnelChannel
|
|
57
57
|
const client = TunnelClient.create({ webServiceUrl, staticUrl });
|
|
58
58
|
client.attach(connector);
|
|
59
59
|
|
|
60
|
-
// Hub
|
|
61
|
-
//
|
|
62
|
-
// HTTP framework adapter
|
|
60
|
+
// Hub side: inject an IHubChannel adapter (e.g. the in-package HubHarness or
|
|
61
|
+
// the consumer's container-proxy wrapper), an IStreamSink (the consumer's
|
|
62
|
+
// HTTP framework adapter), an IAuditSink and an ITokenSigner
|
|
63
63
|
const gateway = new SessionGateway(channel, store, audit, logger);
|
|
64
64
|
const proxy = new TunnelProxy(channel, store, logger);
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
|
|
68
|
-
|
|
67
|
+
The tunnel does NOT interpret roles: `TunnelRole` is a free string — mapping
|
|
68
|
+
and RBAC belong to the consumer. Detailed protocol: [`../docs/LIB-MIMARISI.md`](../docs/LIB-MIMARISI.md)
|
|
69
|
+
and [`../docs/CONTRACTS.md`](../docs/CONTRACTS.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "zero-trust-application-channel",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "Zero-trust application channel core: binary frame codec, v2 wire protocol, peer connector, stream multiplexing client, session gateway and HTTP/WS tunnel proxy. Transport-only, domain-free.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Ilteris Yucel",
|