nexus
Core guides

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

InputSupplied byPurpose
ConnectionTargetThe connecting applicationAn exact address accepted by the adapter
ContextMetaThe remote applicationDeclared identity, roles, and application labels
ConnectionMetaThe local adapterFacts 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.

Edit this page on GitHub