Identity And Metadata
Identify peers, select connections, and distinguish declared identity from observed facts.
When several contexts participate, applications need to distinguish their roles, workspaces, or readiness. Nexus exchanges a small identity object during the handshake and exposes it on the Connection.
Three Different Inputs
| Input | Supplied by | Purpose |
|---|---|---|
| ConnectionTarget | The connecting application | An exact address accepted by the adapter |
| ContextMeta | The remote application | Declared identity, roles, and application labels |
| ConnectionMeta | The local adapter | Facts observed or verified for this session |
A target chooses where to connect. Metadata describes the established peer and connection. Each has a different source and trust boundary.
Declare Local Identity
With explicit endpoint configuration, supply identity in endpoint.meta:
app.configure({
endpoint: {
implementation: endpoint,
meta: {
context: "document-source",
workspace: "drafts",
documentsReady: false,
},
},
});This is a configuration fragment: app and endpoint must share a model that
declares those fields. First-party adapter helpers configure their standard
identity; see the relevant adapter guide.
Keep identity small and serializable. Roles, workspace labels, and readiness can belong here. Secrets, mutable service data, and adapter-observed facts do not.
Read And Select Peers
connection.contextMeta is the latest committed remote identity.
connection.connectionMeta contains local adapter facts for that session.
Use both in a connection predicate:
const connection = await app.connect({
where: (contextMeta, connectionMeta) =>
contextMeta.workspace === "drafts" &&
connectionMeta.observed.authenticated === true,
timeout: 10_000,
});This fragment assumes those fields are declared by your adapter model. Without a
target it waits passively for one match. where constrains acquisition; it does
not discover providers or authorize subsequent calls.
Labels such as groups are ordinary application metadata, not built-in routing
groups. Use predicates to interpret them. A fixed ConnectionCollection does not
change membership when labels change.
Update Identity
await app.updateIdentity({ documentsReady: true });Updates affect the local endpoint’s declared identity. They do not mutate adapter
facts or change the connection’s target. Observe the peer with
connection.subscribeIdentity(listener), which delivers the complete current
identity and later accepted snapshots. See
Connection lifecycle for readiness ordering.
Understand Trust
ContextMeta is peer-declared unless your adapter documents stronger verification. ConnectionMeta can carry locally observed sender details or authentication results, but each fact is only as strong as the adapter’s guarantee.
Use authorization policy for access control.
An application label such as role: "admin" is not by itself proof of authority.
Associate Types With AdapterModel
An AdapterModel associates the three type families:
import type { AdapterModel } from "@nexus-js/core";
interface DocumentModel extends AdapterModel {
contextMeta: {
context: "document-source" | "viewer";
workspace: string;
documentsReady: boolean;
};
connectionMeta: { observed: { authenticated: boolean } };
connectionTarget: { address: string };
}This illustrates a custom model, not an implementation of an adapter. Use the
first-party model and exact target constructors for existing adapters.
Nexus<M>, IEndpoint<M>, and model-bound Tokens share the association.
It provides compile-time consistency, not runtime validation or authentication.