atxp

package module

v1.3.0 Latest Latest Go to latest Published: Jun 16, 2026 License: MIT Imports: 16 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/atendi9/atxp

Links

Open Source Insights

README ¶

ATXP (Atendi9 Transmission Exchange Protocol)

A lightweight, encrypted application wire protocol for fast, structured communication over raw TCP or TLS. Every frame is encrypted with AES-256-GCM under a key derived from a shared password — the password is never transmitted. This repository provides cross-ecosystem implementations for both Node.js (NPM) and Go (Golang) with a byte-identical wire format.

⚠️ About V1. The original ATXP was a proof of concept: it sent credentials and payloads in cleartext and its text delimiters (\t\t, \n\n, ::) collided with arbitrary binary data, corrupting PDFs and other files. It is insecure and deprecated — this README documents only the secure V2 protocol. The V1 symbols remain in the codebase for backward compatibility but must not be used on untrusted networks.

📦 Installation

Node.js (NPM)

npm install @atendi9/atxp-protocol

Go (pkg.go.dev)

go get -u github.com/atendi9/atxp

🔐 Why V2 is secure

Property	Mechanism
Confidentiality	AES-256-GCM encrypts the whole frame.
Integrity	GCM authentication tag detects any tampering.
Authentication	Implicit — only a peer holding the shared password derives the key that opens frames.
Secret never on the wire	Key is derived from the password via PBKDF2-HMAC-SHA256; the password itself is never sent.
Binary-safe	Length-prefixed binary envelope carries PDFs/images losslessly.
DoS resistance	Frame cap (16 MiB default, configurable), bounded reads, and I/O deadlines.
Replay resistance	Strictly increasing per-connection sequence numbers.

Full details in docs/protocol.md and docs/security.md.

🛠️ Usage Guide: Node.js

1. Initialize a Secure Server

import { ServerV2, MT, ResponseCode, AuthData, validateURLHandler } from '@atendi9/atxp-protocol';

// The shared password derives the encryption key. Authorization is by username
// only — possession of the password is already proven by successful decryption.
const server = new ServerV2('shared-secret', (username) => {
  if (username === 'atendi9') {
    return { authorized: true, data: new AuthData({ role: 'admin' }) };
  }
  return { authorized: false, data: new AuthData(null) };
});

server.registerHandler(MT.URL, validateURLHandler());

server.registerHandler(MT.DOCUMENT, (msg) => {
  console.log(`[Document Received]: ${msg.filename || 'unknown'}, ${msg.data.length} encrypted bytes`);
  return ResponseCode.OK;
});

const listening = await server.listen(8443);
console.log('ATXP V2 server running on port 8443');

2. Initialize a Secure Client

import net from 'node:net';
import { newClientV2 } from '@atendi9/atxp-protocol';

const socket = net.createConnection({ port: 8443 }, async () => {
  // newClientV2 performs the encrypted handshake before resolving.
  const client = await newClientV2(socket, 'shared-secret', 'atendi9');

  // A binary PDF travels fully encrypted and arrives intact.
  const fileBuffer = Buffer.from('%PDF-1.7\n...binary content...');
  const code = await client.sendDocument(fileBuffer, 'annual_report.pdf');
  console.log(`Server returned: ${code}`);

  client.close();
});

🐹 Usage Guide: Go (Golang)

1. Initialize a Secure Server

package main

import (
    "fmt"
    "log"

    "github.com/atendi9/atxp"
    "github.com/atendi9/box"
)

func main() {
    // The shared password derives the per-connection key; auth is by username.
    server, err := atxp.NewServerV2("shared-secret", func(username string) (bool, atxp.AuthData) {
        if username == "atendi9" {
            return true, box.NewSome(map[string]any{"role": "admin"})
        }
        return false, box.NewNone[map[string]any]()
    })
    if err != nil {
        log.Fatalf("Failed to create server: %v", err)
    }

    server.RegisterHandler(atxp.DOCUMENT, func(msg *atxp.Message, _ atxp.AuthData) atxp.ResponseCode {
        fmt.Printf("[Go Server] Document %q received, %d encrypted bytes\n", msg.Filename, len(msg.Data.Get()))
        return atxp.OK
    })

    listener, err := atxp.CreateServer(8443)
    if err != nil {
        log.Fatalf("Failed to bind listener: %v", err)
    }

    fmt.Println("ATXP V2 Go server listening on port 8443...")
    if err := server.Serve(listener); err != nil {
        log.Fatalf("Server loop failed: %v", err)
    }
}

2. Initialize a Secure Client

package main

import (
    "fmt"
    "log"

    "github.com/atendi9/atxp"
)

func main() {
    conn, err := atxp.ConnectClient("127.0.0.1", 8443)
    if err != nil {
        log.Fatalf("Failed to dial host: %v", err)
    }

    // NewClientV2 performs the encrypted handshake on construction.
    client, err := atxp.NewClientV2(conn, "shared-secret", "atendi9")
    if err != nil {
        log.Fatalf("Handshake failed: %v", err)
    }
    defer client.Close()

    documentBytes := []byte("%PDF-1.7\n...binary content...")
    status, err := client.SendDocument(documentBytes, "report.pdf")
    if err != nil {
        log.Fatalf("Failed to send frame: %v", err)
    }

    fmt.Printf("Server returned status: %v\n", status)
}

🧩 Registering custom message types

V2 message types are registrable at runtime. Codes must be unique and fit in a uint32.

atxp.NewMT(atxp.MT_V2{Name: "WEBHOOK", Code: 100, Description: "external webhook registration"}) // Go

newMT({ name: 'WEBHOOK', code: 100, description: 'external webhook registration' }); // JS

Then send with the custom code:

client.Send(100, payload, "")            // Go

await client.send(100, payload, '');     // JS

📏 Tuning the frame size cap

Each encrypted frame is capped at 16 MiB by default to bound memory use. Beefier servers that must transfer larger documents can raise the cap — and constrained environments can lower it. Set it on both the server and the client (a sender's cap must not exceed the receiver's, or large frames are rejected):

// Go — 64 MiB cap. Values below the minimum valid frame size are ignored.
server, _ := atxp.NewServerV2("shared-secret", authFn, atxp.WithMaxFrameSize(64<<20))
client, _ := atxp.NewClientV2(conn, "shared-secret", "atendi9", atxp.WithMaxFrameSize(64<<20))

// Node.js — 64 MiB cap via the options object.
const server = new ServerV2('shared-secret', authFn, { maxFrameSize: 64 * 1024 * 1024 });
const client = await newClientV2(socket, 'shared-secret', 'atendi9', { maxFrameSize: 64 * 1024 * 1024 });

📑 V2 Wire Protocol Specification

Each connection begins with a server-initiated handshake, after which every frame is encrypted.

Handshake (22 bytes, server → client):

"ATXP2" (5B magic) | version (1B = 0x02) | salt (16B random)

Both peers derive K = PBKDF2-HMAC-SHA256(password, salt, 600000, 32).

Encrypted frame (both directions):

length (4B BE uint32) | nonce (12B) | AES-256-GCM(ciphertext + tag)

Inner plaintext envelope (length-prefixed, binary-safe):

kind (1B)            # 0x01 = Message, 0x02 = Response
seq  (8B BE uint64)  # monotonic per connection (anti-replay)
mtCode      (4B BE) | payloadLen (4B) | payload | userLen (4B) | username | fnameLen (4B) | filename

There is no password field anywhere on the wire. See docs/protocol.md for the complete specification, including cross-language known-answer test vectors.

Built-in Message Types

Name	`MT.X` (Node.js)	`atxp.X` (Go)	Code	Description
URL	`MT.URL`	`atxp.URL`	`0`	URLs / webhook registration.
DOCUMENT	`MT.DOCUMENT`	`atxp.DOCUMENT`	`1`	Binary file transfer with optional filename.
NOTIFICATION	`MT.NOTIFICATION`	`atxp.NOTIFICATION`	`2`	JSON or events for event-driven architectures.

📜 License

Distributed under the terms of the open-source MIT License.