Bridge contracts

@genation/bridge-contracts is the portable single source of truth for Genation Bridge protocol contracts. It provides runtime schemas and TypeScript types that Bridge components and peer implementations can share without depending on backend infrastructure.

Public imports

Import contracts from the package root or one of its five documented subpaths. Relative imports are preferred within the package itself.

• @genation/bridge-contracts
• @genation/bridge-contracts/grants
• @genation/bridge-contracts/wire
• @genation/bridge-contracts/metadata
• @genation/bridge-contracts/errors
• @genation/bridge-contracts/sdk

Compatibility and versioning

json.v1 is the protocol compatibility boundary. Additive, compatible changes can remain in json.v1. Removing or renaming fields, changing their meaning, or tightening accepted wire values requires a new protocol or schema version and a migration.

Peer grants use the separate grant.v2 contract. Its optional authorization envelope contains a bounded opaque subject and typed, RAR-shaped business details. Bridge validates and signs this metadata but never interprets fields such as actions; the receiving customer handler owns their meaning and enforcement. grant.v1 is no longer accepted.

Generated artifacts

Generate or verify all derived artifacts from the repository root with these commands.

deno task contracts:generate
deno task contracts:check-generated

Generated JSON Schema files are stored in generated/json-schema/, the normative language-neutral protocol manifest is stored in protocol/manifest/, and conformance vectors are stored in test-vectors/v1/. These deterministic artifacts are checked into the repository, and the freshness check fails when derived artifacts don't match their TypeScript source.

Cryptographic execution lives in the sibling packages/crypto-core Rust crate. SDKs consume its prebuilt bindings while using this package as the public protocol and provider contract.

Privacy boundary

The public metadata contract intentionally distinguishes observable routing data from customer content and secrets.

Capability names, peer identifiers, routing timestamps, lifecycle outcomes, Bridge codes, approved byte counts, and optional grant authorization are observable signed metadata. Raw customer credentials, inputs, outputs, error content, stacks, private keys, and session keys remain outside public metadata and must never be logged or persisted by Bridge. Authorization must contain opaque identifiers and policy hints, not JWTs, cookies, secrets, or directly identifying personal data.

Non-goals

This package defines portable contracts only. It doesn't provide or own these runtime responsibilities.

• Transport implementation
• Cryptographic execution
• Key storage
• Backend adapters
• Customer authentication