B3nd Canon

Protocol-building toolkit for B3nd. Message envelopes, content addressing, access control, and encryption -- the pieces a protocol designer composes on top of the core framework.

GitHub

Depends on @bandeira-tech/b3nd-core for types and encoding.

Message Layer

The message primitive is [uri, payload]. When the payload follows the MessageData convention it carries { auth, inputs, outputs } -- a signed envelope that the rig decomposes into individual writes.

import {
  message,
  messageDataHandler,
  messageDataProgram,
} from "@bandeira-tech/b3nd-canon/msg";
import {
  connection,
  DataStoreClient,
  Identity,
  MemoryStore,
  Rig,
} from "@bandeira-tech/b3nd-core";

const client = new DataStoreClient(new MemoryStore());

const rig = new Rig({
  routes: {
    receive: [connection(client, ["*"])],
    read: [connection(client, ["*"])],
  },
  programs: { "hash://sha256": messageDataProgram },
  handlers: { "msgdata:valid": messageDataHandler },
});

const id = await Identity.generate();
const auth = [
  await id.sign({ inputs: [], outputs: [["mutable://open/x", { v: 1 }]] }),
];
const envelope = await message({
  auth,
  inputs: [],
  outputs: [["mutable://open/x", { v: 1 }]],
});
// envelope = ["hash://sha256/{hex}", { auth, inputs, outputs }]

await rig.send([envelope]);
// The handler decomposes the envelope: persists the envelope at hash://,
// writes each output to its destination URI, and nullifies inputs.

Content Addressing

Hash-based URIs using hash://sha256/{hex}. JSON payloads canonicalized per RFC 8785 before hashing.

import {
  computeSha256,
  generateHashUri,
  verifyHashContent,
} from "@bandeira-tech/b3nd-canon/hash";

const hash = await computeSha256({ hello: "world" });
const uri = generateHashUri(hash);
// "hash://sha256/93a23971a914e5eacbf0a8d25154cda309c3c1c72fbb9914d47c60f3cb681588"

const result = await verifyHashContent(uri, { hello: "world" });
// { valid: true, algorithm: "sha256", digest: "93a2..." }

Hash Validator

Write-once enforcement for content-addressed storage:

import { hashValidator } from "@bandeira-tech/b3nd-canon/hash";

const rig = new Rig({
  routes: { ... },
  programs: { "hash://sha256": hashValidator(readFn) },
});

Access Control

Signature-based access control that composes with the rig as programs.

import {
  authValidation,
  createCombinedAccess,
  createPubkeyBasedAccess,
} from "@bandeira-tech/b3nd-canon/auth";

// Pubkey-based: mutable://accounts/{pubkey}/* requires matching signature
const pubkeyAccess = createPubkeyBasedAccess(readFn);

// Combined: pubkey namespace + relative path access lists
const access = createCombinedAccess(readFn);

// Wire into rig as a program
const validate = authValidation(access);

Encryption

Ed25519 signing, X25519 encryption, AES-GCM symmetric, and PBKDF2 key derivation. Shared with b3nd-core (Identity needs it).

import {
  createAuthenticatedMessage,
  decrypt,
  encrypt,
  generateEncryptionKeyPair,
  generateSigningKeyPair,
  sign,
  verify,
} from "@bandeira-tech/b3nd-canon/encrypt";

// Sign a payload
const keys = await generateSigningKeyPair();
const signature = await sign(keys.privateKey, { action: "transfer" });
const valid = await verify(
  keys.publicKeyHex,
  { action: "transfer" },
  signature,
);

// Encrypt (X25519 ECDH + HKDF + AES-GCM, forward secrecy via ephemeral keys)
const encKeys = await generateEncryptionKeyPair();
const encrypted = await encrypt(
  new TextEncoder().encode("secret"),
  encKeys.publicKeyHex,
);
const plaintext = await decrypt(encKeys.privateKeyHex, encrypted);

Libraries

| Library | Description | | -------------- | ----------------------------------------------------------------------- | | b3nd-msg | Message envelopes, MessageData convention, program + handler | | b3nd-hash | Content addressing (hash://sha256), link URIs, write-once validator | | b3nd-auth | Pubkey-based access control, relative path access, signature validation | | b3nd-encrypt | Ed25519, X25519, AES-GCM, PBKDF2, authenticated messages, PKCE |

Subpath Exports

import { ... } from "@bandeira-tech/b3nd-canon";           // everything
import { ... } from "@bandeira-tech/b3nd-canon/msg";       // message layer
import { ... } from "@bandeira-tech/b3nd-canon/hash";      // content addressing
import { ... } from "@bandeira-tech/b3nd-canon/auth";      // access control
import { ... } from "@bandeira-tech/b3nd-canon/encrypt";   // encryption & signing

Development

deno check src/mod.ts       # Type check
deno test libs/              # Run tests

Project Structure

src/           # Entry points and subpath re-exports
libs/          # 4 libraries (see table above)

Related

• b3nd-core -- framework foundation (types, rig, clients, network)
• b3nd-sdk -- SDK umbrella that re-exports core + canon

License

MIT