Local Peer-to-Peer API

Note: This specification is under active development and therefore incomplete. If you’re looking for an overview of the proposal, please refer to the Explainer.

1. Introduction

This section is non-normative.

The Local Peer-to-Peer API aims to give browsers the means to communicate directly, without the aid of a server in the middle. It is designed to enable this communication within the confines of a local communication medium.

Many modern Web security measures rely on the presence of naming, signaling and certificate authorities. Local use-cases where these authorities are not readily available have started lagging behind in user experience or are not supported altogether. The Local Peer-to-Peer API aims to bring back first-class support for local communication use-cases while working within the same strict user-friendliness, security and privacy requirements.

Examples of potential uses of this API include: Collaboration tools that work during an internet outage or emergency situations, connecting to your NAS, your home security system, your robotic assistant doing the dishes or your GPU farm in the basement that’s running your personalized virtual assistant. See also Use Cases.

This specification aims to strike a balance between creating a powerful new building block for developers and providing a seamless, secure and privacy preserving experience for browser users. As an example: while the API doesn’t provide raw socket access, it does aim to give developers the flexibility to innovate on top by providing a persistent, two-way communication channel with little overhead.

The API is designed to be backed by an authenticated, streams-based transport. It is defined against the abstract operations of § 6 Transport abstraction, which a transport binding maps onto a concrete protocol. As a commitment to an open standards-based implementation path, this specification defines a binding to the Open Screen Network Protocol in § 15 Binding to the Open Screen Network Protocol. Other bindings are anticipated, for example WebTransport over QUIC with peers authenticated on the local network as explored by the IETF SETTLE working group.

2. Terminology

The term local communication medium refers to a communication medium that provides a local, direct communication channel between the communicating devices. It carries IP between the devices, directly or through a local network, for example a wired or wireless local area network or Wi-Fi Direct. Discovery and authentication may also use other channels, such as Bluetooth Low Energy, NFC or a QR code. This spec will not mandate which underlying technologies must be supported. Being on it is not a security property; see § 14.5 Authentication and locality.

The term local communication refers to data communication over the local communication medium.

The term communication medium topology refers to the composition of the local communication medium which may include sensitive information such as IP or other address information or the number of devices connected to the medium.

3. Permission Policy Integration

The Local Peer-to-Peer API defines a policy-controlled feature identified by the token "local-peer-to-peer". Its default allowlist is "self".

Workers (dedicated and shared) adhere to the permission policy set by their owning document(s):

• Dedicated workers can be created from other workers, in which case the permission policy of the first owning document (in case of a dedicated worker) or owning documents (in case of a shared worker) up the owner chain will be used.
• Shared workers often have multiple owning documents as they can be obtained by other documents with the same origin. In this case, all owning documents must be allowed to use the policy-controlled feature defined by this specification.

Note: There has been discussion on allowing setting permission policy directly on a worker on creation, in which case that would have to be consulted as well.

The user interface that a global object global needs, such as the picker or a prompt, is shown for its user interface document, and the user’s consent there is consent for global’s relevant settings object’s origin. For a Window, it is its associated Document. For a dedicated worker, it is that of its owner, up the owner chain. For a shared worker, it is one of its owning documents that is fully active and whose visibility state is "visible", chosen by the user agent. If there is none, or it is not fully active, the user agent treats the user interface as dismissed: start() and start() reject with a "NotAllowedError" DOMException, and an incoming session that needs a prompt is refused.

Decide whether to expose this API in service workers, which have no document to show user interface or to own consent.

The default allowlist of "self" allows usage in same-origin nested frames but prevents third-party content from using the feature. Third-party content usage can be selectively enabled by adding allow="local-peer-to-peer" attribute to the frame container element:

<iframe src="https://third-party.com" allow="local-peer-to-peer"/></iframe>

Alternatively, the Local Peer-to-Peer API can be disabled completely by specifying the permissions policy in a HTTP response header:

Permissions-Policy: local-peer-to-peer=()

See [PERMISSIONS-POLICY] for more details.

4. Peer Management

Note: This section and its subsections use RFC 2119 terminology in a relaxed manner. These sections will be converted into well-defined algorithmic normative prose informed by further implementation experience. For now, this relaxed description better allows for rapid prototyping.

The user agent is in charge of managing peers.

A peer is an equal participant in the local communication. These nodes can communicate without the need for a central coordination by a server.

A user agent has an associated local peer-to-peer manager in charge of managing peers. Its responsibility is to start local peer discovery, establish sessions and acquire a local peer grant on a per-origin basis. This is done to avoid exposing information about the communication medium topology.

4.1. Local state

The local peer-to-peer manager has:

local trust store

A set of trust anchors, see § 4.5 Peer authentication.

known peers map

An ordered map from peer identity to known peer: a peer the user agent has had an authenticated session with, which the user selected or accepted.

peer grants

A set of tuples of an origin, a peer identity that the origin may use, and a requesting origin. The requesting origin is "selected" for a peer the user selected in acquire a local peer grant. For a peer whose incoming session the user accepted, it is the session’s requesting origin, possibly null, so the grant covers only sessions requested on behalf of that origin, or with no origin. An origin has a peer grant for a peer identity if the peer grants contain a tuple with both.

A known peer records the anchor key and subject it last chained to on an authenticated session, or null. Whether it is authenticated is not stored: without a live session, it is evaluated on these, against the local trust store. So removing a trust anchor can tell which peers are no longer authenticated.

The state is changed only by the operations below. How it is stored is implementation-defined.

Other specifications can define trust anchor checks: steps that, given a trust anchor, return whether it may be added to the local trust store. Local HTTPS uses one to keep at most one key per host.

When an origin’s site data or permissions are cleared, the user agent runs revoke a peer grant given that origin and each peer identity it has a peer grant for.

Note: Peer grants are origin-level while the local trust store is shared by all origins, so that the user doesn’t need to authenticate the same peer again for every origin. Origins are kept apart by the peer grants and by the requesting origin of each session. Peer grants could be stored as the origin’s permission data in the permission store, as Web Bluetooth does for its allowed devices.

Decide whether to back peer grants with the permission store, as the extra permission data of a "local-peer-to-peer" powerful feature, which would also give a permission query and revocation.

Validate that a local trust store shared by all origins is appropriate, or whether trust anchors should be partitioned, for example per top-level site. [WICG/local-peer-to-peer Issue #24]

The user agent may persist its local trust store, known peers and/or peer grants. If the user agent chooses to do so, it must do so in accordance with the persistent state rules of the transport binding in use. Such state is said to be persisted. Results of discover peers, such as addresses, are not part of this state.

When the user clears all browsing data, the user agent clears its local trust store, known peers map and peer grants, and replaces its own credentials. Each user profile and each private browsing session has its own.

4.2. Trust lifecycle

Trust relationships are visible, reviewable and removable: the user agent must let the user view the trust anchors, known peers and peer grants, and remove them, with remove a trust anchor, forget a known peer and revoke a peer grant. Removal revokes: it closes the sessions that relied on what was removed, including sessions still being set up. Removing a peer in the user interface runs forget a known peer and also removes the one peer trust anchor for it, so that it is no longer authenticated. User agents should bound trust over time, for example by letting trust anchors or peer grants expire, or by asking the user to review those not used for a long period.

Note: No online authority can revoke a peer. Removal by the user, and trust bounded in time, take its place. A vouching party also bounds the validity of the credentials it vouches for, see § 5 Vouching and delegated trust.

4.3. Peer advertisement

The user agent can make itself discoverable by advertising, using start advertising.

Note: The user agent must get the user’s explicit consent in order to start advertising.

When advertising, the user agent must listen for incoming sessions. The user agent must not directly provide access to an incoming session to any origin. Instead, unless the origin that initiated peer advertisement already has a peer grant for the peer and the session’s requesting origin, the user agent must prompt to grant peer access to that origin. Accepting the incoming session runs grant a peer for both, so later sessions from the peer on behalf of the same requesting origin do not prompt again; only then does the user agent run add a known peer with the peer. See § 7.1 Incoming sessions.

The user agent must deliver an incoming session only to the LP2PReceiver whose advertisement it was reported for, if that receiver is started and allows the session’s requesting origin, and refuse the session otherwise. It never delivers the session to another receiver instead. A refusal is indistinguishable, to the client, from the user declining. An LP2PReceiver allows an origin origin, an origin or null, if its [[AllowAnyRequester]] is true, or if origin is neither null nor an opaque origin, and is same origin with the receiver’s relevant settings object’s origin or with an item of its [[AllowedOrigins]].

4.4. Peer discovery

When asked to start local peer discovery, the user agent runs discover peers.

Discovered peers and their advertisements are only shown in the picker, see acquire a local peer grant; they are not known peers, whose entries are added or updated only from authenticated sessions, by add a known peer. The user agent must never expose the full result of peer discovery with an origin. Instead, the user agent must acquire a local peer grant to grant access to a peer for the origin that initiated the peer request.

4.5. Peer authentication

A trust anchor is a key that the user agent trusts to authenticate peers. It has:

key

The key that peers' credentials chain to. What the credentials are, and how they chain to a key, is defined by the transport binding.

scope

Either one peer, a single peer that the anchor vouches for, or vouching, any peer the anchor vouches for, within the limits of § 5 Vouching and delegated trust.

A trust anchor is added to the local trust store only by a trust ceremony: a run of authenticate a session in which the user takes part, for example by entering a PIN or scanning a QR code. A trust ceremony with a peer runs add a trust anchor scoped to one peer: that peer, unless the user chooses to trust a vouching party for its devices, see § 5 Vouching and delegated trust. If add a trust anchor returns failure, the ceremony fails.

A peer that uses its own key is self-anchored: its trust anchor is its key, scoped to one peer, that peer.

On the server, a trust anchor that a trust ceremony added is kept only if the user accepts the session; otherwise it is removed, see § 7.1 Incoming sessions. On the client, it is kept even if the server then refuses the session: the user chose to pair with the device, and a refusal concerns the requesting origin, not trust.

A peer is said to be authenticated when its credentials chain to the key of a trust anchor in the local trust store, and the peer is within that anchor’s scope.

A peer whose claimed peer identity is that of a known peer, but whose credentials do not chain to that peer’s anchor key, is not that known peer. The user agent must not mark it as known, and must warn the user that it may not be the device they know before running a trust ceremony with it.

A peer’s credentials may change over time without changing its peer identity, as long as they chain to the same key. Whether a key can be replaced with continuity is defined by the transport binding; if so, the user agent runs replace a trust anchor key. Otherwise, a new key needs a new trust ceremony.

Define how a peer can move to another trust anchor’s key while keeping its peer identity and peer grants, for example by proving that it holds both keys.

Note: Trust anchors may also be used to validate HTTPS servers on the local communication medium, each constrained to a namespace of local names; see the separate Local HTTPS draft.

4.6. Peer grant

The user agent, with the user’s consent, must acquire a local peer grant for an origin to get access to a peer.

Note: The user agent must get the user’s explicit consent in order to grant an origin access to a peer. For enhanced privacy protection, the user agent must provide means to dismiss any related user interface and this action must not be detectable by script or have script-observable side-effects. The user interface may provide means to revoke the grant or to make the grant persisted.

When asked to acquire a local peer grant for an origin, the user agent displays the advertisements that discover peers reports to the user through its native user interface, each with its nickname and its peer, and returns the advertisement the user selects, or null if the user dismisses the user interface. It marks a peer as known if it claims the peer identity of a known peer, and a peer that claims to be vouched for as new, with the name of the vouching party; these claims are only verified once a session with the peer is authenticated. The user agent may leave out peers whose capabilities lack the features the page needs. Selecting an advertisement is the user’s consent. Once a session with its peer is authenticated as the peer the user selected and accepted, the user agent runs grant a peer for the origin. See start().

5. Vouching and delegated trust

A vouching party, such as a home hub, issues credentials to other peers, so that the user does not need a trust ceremony with each of them. Whether a peer is a vouching party is defined by the transport binding.

The user trusts a vouching party for its devices only in a trust ceremony with the vouching party itself, as a separate choice from pairing with it as one device. The ceremony then runs add a trust anchor with the party’s key scoped to vouching, which removes the one peer trust anchors with that key; their peers keep their peer identities. Its user interface says which devices the choice covers, including those already paired, and that removing it removes trust in all of them.

A peer whose credentials chain to a vouching trust anchor is authenticated: its peer identity and the display name that the vouching party attests are trusted. Until the user confirms it, it is unconfirmed: the user agent must not run add a known peer with it, and Local HTTPS does not trust its hosts for navigations the user initiates. The user confirms a peer by selecting it in acquire a local peer grant, or by accepting its incoming session in § 7.1 Incoming sessions; for an unconfirmed peer, both name the vouching party. This is a single choice, such as "Connect to printer.home.local? Vouched for by Home.", not a trust ceremony.

Note: Confirmation is not verification: a vouching party can attest a misleading name. Confirmation makes each of its devices visible to the user once, so a compromised vouching party cannot silently add trusted devices; it still authenticates whatever it vouches for until the user removes it.

A transport binding that supports vouching parties must ensure that:

• a vouching party is recognized from its credentials, not from a claim, such as one made in discovery;

• each credential it vouches for names a subject, stable and unique under the vouching party, and a display name it attests;

• limits on what it may vouch for can be expressed and are enforced, at least a namespace of names;

• the credentials it vouches for have a bounded validity, so that a compromise ages out without a revocation service;

• the user agent can tell, during authenticate a session, a peer vouched for from one anchored directly.

Note: A vouching party corresponds to the referee of REQ-ARCH-02 in the IETF SETTLE requirements: a name-constrained certificate authority for local names. The requirements above are input to that work.

6. Transport abstraction

The API and its algorithms are defined against the abstract concepts and operations in this section. A transport binding defines how a concrete protocol implements them. This specification defines one transport binding, in § 15 Binding to the Open Screen Network Protocol. Which bindings a user agent implements is implementation-defined. A peer is associated with the binding through which it was discovered or through which its session arrived, and all operations involving that peer use that binding.

A transport binding must provide end-to-end confidentiality and integrity for all communication with a peer, including when the path to the peer goes through an intermediary.

6.1. Peers and sessions

A peer has the following, provided by its transport binding. None of them is exposed to an origin.

peer identity

An opaque value that identifies the peer, stable across sessions, scoped to the transport binding. It is derived from the key that the peer’s credentials chain to and the peer’s subject under it; for a self-anchored peer, the subject is its own key. It is only trusted once the peer is authenticated. The known peers map and peer grants are keyed on it.

display name

A name for the peer device, for display in user agent user interface, or null. It is asserted by the peer’s user agent, not by script. Trusted only if obtained on a session that is or becomes authenticated, or by other means the user agent considers trustworthy; otherwise, such as during discover peers, it is a display hint.

capabilities

The set of features the peer supports: data channels and WebTransport. Like the display name, it is asserted by the peer’s user agent and is only a hint until the peer is authenticated.

A user agent refuses an incoming data channel or incoming WebTransport session for a feature it has not enabled.

A Local Peer-to-Peer session is a confidential connection with one peer. It is authenticated if the credentials the peer presented in it chain to a trust anchor in the local trust store, which verifies the peer identity of the peer for it.

A Local Peer-to-Peer session that is exposed to an origin is not shared with other origins. A binding may carry several sessions with the same peer over one underlying connection, or use a separate connection for each.

For each Local Peer-to-Peer session, the side that established it with establish a session is the client, and the side that reported it as an incoming session is the server. Once established, the session is symmetric: either side can use any operation on it, except that:

• the server validates the requesting origin;

• where the binding needs it to avoid collisions, identifiers such as ids and streams follow the role;

• only the client opens any additional underlying connection for the session.

A Local Peer-to-Peer session that is exposed to an origin has a requesting origin: the origin on whose behalf the client established it, or null if the requester has no origin, as for a native application or headless device. A user agent always conveys the origin of the page. The client conveys it inside the session, and the transport binding binds it to the authenticated session, for example by carrying it on the channel that authentication covers. The server checks it as described in § 4.3 Peer advertisement.

The requesting origin reveals which sites the user is using, and the origins that a server accepts reveal which sites its user is using. Neither is exposed to a peer that is not authenticated. A transport binding may let the server find out earlier whether it would accept the requesting origin, so that a trust ceremony is not wasted on a session it refuses, only with a mechanism that exposes neither. Otherwise, a first trust ceremony with a peer can end in a refusal.

Follow up on REQ-NAME-05, "Privacy-Preserving Discovery", of the IETF SETTLE requirements, for a mechanism that lets a server decide earlier without exposing either side’s origins.

The requesting origin is asserted by the peer’s user agent. The binding guarantees that it is consistent for the session, not that it is authentic: it does not prove that the remote page was served by that origin. User agents must not grant anything that belongs to the requesting origin, such as its permissions, storage or credentials, on the strength of it, and neither must any other implementation of a peer, such as device logic; see § 14.5 Authentication and locality. This is the same model as the Origin header in [FETCH].

Device keys, credentials and anything else that would let an origin authenticate as the user agent must not be exposed to origins. Instead, each WebTransport session has its own keying material exporter, see export keying material, so that applications can prove their origins with credentials their own origin issued.

A data channel is a reliable, ordered, message-preserving, bidirectional channel on a Local Peer-to-Peer session. Either side can open one. It has an id, an integer between 0 and 65,534 that is unique within the session, a label and a protocol. A message on a data channel is a sequence of bytes, marked as either text or binary.

6.2. Operations

A transport binding provides the following operations. Any of them can fail, including because the peer does not support it.

To start advertising given a nickname

Make the user agent discoverable through discover peers on other user agents and accept sessions from peers. This returns a new advertisement, which has the given nickname, chosen by script and never verified, if the binding can carry it, and an advertisement ID: a random value, new for each advertisement, that names it to peers. Each Local Peer-to-Peer session a peer establishes with it is reported as an incoming session for that advertisement. To stop advertising given an advertisement ends both.

To discover peers

Report the advertisements on the local communication medium, each with its nickname and its peer, with the peer’s display name and capabilities as far as the binding knows them, as they appear and disappear, until asked to stop discovering peers. A discovered peer identity is not verified.

To establish a session with an advertisement given an origin

Establish a Local Peer-to-Peer session with the advertisement’s peer, with that origin as its requesting origin. On the peer, the session is reported as an incoming session for that advertisement, which the peer’s user agent later accepts or refuses. The client is notified of either. Refusing closes the session. The binding names the advertisement inside the session, covered by authentication, so that the session cannot be reported for another advertisement of the same peer.

To authenticate a session

Mutually authenticate the two sides of a Local Peer-to-Peer session and verify the peer identity of the peer, so that the session is authenticated. If the peer’s credentials do not chain to a trust anchor in the local trust store, this is a trust ceremony, which requires user interaction on one or both devices and runs add a trust anchor as described in § 4.5 Peer authentication. Only the client initiates it; the server only responds.

To open a data channel on an authenticated Local Peer-to-Peer session given a label, a protocol and an optional id

Open a data channel with that label and protocol, and with the given id or, if none is given, one chosen by the binding. The other side is notified of an incoming data channel, which its user agent accepts or refuses. The operation succeeds if it is accepted.

To send data on a channel given a data channel and a message

Queue the message for delivery on the data channel. The other side is notified of a received message.

To close a data channel

Close the data channel in both directions. The other side is notified that it was closed.

To close a session

Close the Local Peer-to-Peer session, all of its data channels and, abruptly, all of its WebTransport sessions. The other side is notified that it was closed. The binding also reports a session as closed when the underlying transport fails.

To open a WebTransport session over an authenticated Local Peer-to-Peer session

Establish a session with the same peer that provides the capabilities of a WebTransport session as defined in [webtransport], bound to the same peer identity. The other side is notified of an incoming WebTransport session, which its user agent accepts or refuses. The operation succeeds if it is accepted. The session either delivers datagrams unreliably ("supports-unreliable") or, if the binding cannot lose messages, reliably ("reliable-only"), as WebTransport over HTTP/2 does.

To close a WebTransport session given a close code and a reason

Close the WebTransport session and its streams. The other side is notified that it was closed, with that code and reason. The Local Peer-to-Peer session stays open. The binding also reports a WebTransport session as closed abruptly, without a code and reason, when it fails or its Local Peer-to-Peer session closes.

To export keying material from a WebTransport session given a label, a context and a length

Return keying material of that length that both sides of the WebTransport session derive identically and that no other WebTransport session yields, including one carried over the same underlying connection. The binding derives it as WebTransport over HTTP/3, Section 4.8 does: a TLS exporter [RFC9846] whose context holds an identifier of the WebTransport session, the label and the context. The requesting origin need not be part of it, since a Local Peer-to-Peer session is not shared between origins.

To drain a WebTransport session

Ask the other side to finish using the WebTransport session and close it. Both sides can still use it.

Note: Data channels (LP2PDataChannel) and WebTransport sessions (LP2PQuicTransport) are two independent ways to communicate over a Local Peer-to-Peer session; neither is built on the other.

Decide whether to keep both data channels and WebTransport sessions, or converge on one. [Issue #29]

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PReceiver : EventTarget {
  constructor(optional LP2PReceiverOptions options = {});
  attribute EventHandler onconnection;
  Promise<undefined> start();
  undefined stop();
};

dictionary LP2PReceiverOptions {
    DOMString nickname;
    sequence<USVString> allowedOrigins = [];
};

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PConnectionEvent : Event {
    constructor(DOMString type, LP2PConnectionEventInit connectionEventInitDict);
    readonly attribute LP2PConnection connection;
};

dictionary LP2PConnectionEventInit : EventInit {
    required LP2PConnection connection;
};

const receiver = new LP2PReceiver({
    nickname: "example-receiver",
    // Also accept sessions requested by this origin.
    allowedOrigins: ["https://partner.example"],
});
receiver.onconnection = e => {
    console.log("Connection established!");
    const conn = e.connection;
    conn.onclose = () => console.log("Connection closed.");
};

// Blocks until permission is received.
await receiver.start();

// Later: stop advertising. Delivered connections stay open.
receiver.stop();

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PRequest {
    constructor(optional LP2PRequestOptions options = {});
    Promise<LP2PConnection> start(optional LP2PRequestStartOptions options = {});
};

dictionary LP2PRequestOptions {
    DOMString nickname;
};

dictionary LP2PRequestStartOptions {
    AbortSignal signal;
};

const request = new LP2PRequest({
    nickname: "example-request",
});

try {
    // Blocks until the user picked a peer and it accepted the session.
    const conn = await request.start();
    console.log("Connection established!");

    // Later: close the connection, its data channels and its transports.
    conn.close();
} catch (e) {
    // NotAllowedError: dismissed, refused or failed; script can't tell which.
}

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PConnection : EventTarget {
  undefined close();
  attribute EventHandler onclose;
};

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PDataChannel : EventTarget {
  constructor(USVString label,
              optional LP2PDataChannelInit dataChannelDict = {});
  readonly attribute USVString label;
  readonly attribute USVString protocol;
  readonly attribute unsigned short? id;
  attribute EventHandler onopen;
  attribute EventHandler onerror;
  attribute EventHandler onclosing;
  attribute EventHandler onclose;
  undefined close();
  attribute EventHandler onmessage;
  attribute BinaryType binaryType;
  undefined send((USVString or Blob or ArrayBuffer or ArrayBufferView) data);
};

dictionary LP2PDataChannelInit {
  USVString protocol = "";
  [EnforceRange] unsigned short id;
};

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
partial interface LP2PConnection {
  LP2PDataChannel createDataChannel(USVString label,
                                    optional LP2PDataChannelInit dataChannelDict = {});
  attribute EventHandler ondatachannel;
};

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PDataChannelEvent : Event {
  constructor(DOMString type, LP2PDataChannelEventInit dataChannelEventInitDict);
  readonly attribute LP2PDataChannel channel;
};

dictionary LP2PDataChannelEventInit : EventInit {
    required LP2PDataChannel channel;
};

const receiver = new LP2PReceiver({
    nickname: "example-receiver",
});

receiver.onconnection = e => {
    const conn = e.connection;
    console.log("Receiver: Got a connection!");

    conn.ondatachannel = e => {
        const channel = e.channel;

        channel.onmessage = e => {
            const message = e.data;
            console.log(`Receiver: Received message: ${message}`);
        };

        channel.send("Good day to you, requester!");
    };
};

await receiver.start();

const request = new LP2PRequest({
    nickname: "example-request",
});

const conn = await request.start();
console.log("Requester: Got a connection!");

const channel = conn.createDataChannel("My Channel");

channel.onopen = e => {
    channel.onmessage = e => {
        const message = e.data;
        console.log(`Requester: Received message: ${message}`);
    };

    channel.send("Good day to you, receiver!");
};

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PQuicTransport : WebTransport {
  constructor(LP2PConnection connection,
              optional LP2PQuicTransportInit options = {});
  readonly attribute LP2PConnection connection;
};

dictionary LP2PQuicTransportInit {
  boolean requireUnreliable = false;
  WebTransportCongestionControl congestionControl = "default";
  [EnforceRange] unsigned short? anticipatedConcurrentIncomingUnidirectionalStreams = null;
  [EnforceRange] unsigned short? anticipatedConcurrentIncomingBidirectionalStreams = null;
};

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
interface LP2PQuicTransportListener {
  constructor(LP2PConnection connection,
              optional LP2PQuicTransportListenerInit options = {});
  readonly attribute ReadableStream incomingTransports;
  undefined close();
};

dictionary LP2PQuicTransportListenerInit : LP2PQuicTransportInit {
};

// Receiver
const receiver = new LP2PReceiver({
    nickname: "example-receiver",
});
receiver.onconnection = async e => {
    const listener = new LP2PQuicTransportListener(e.connection);
    for await (const transport of listener.incomingTransports) {
        // Incoming transports are already ready.
        const stream = await transport.createBidirectionalStream();
    }
};
await receiver.start();

// Requester
const request = new LP2PRequest({
    nickname: "example-request",
});
const conn = await request.start();
const transport = new LP2PQuicTransport(conn);
await transport.ready;

[Exposed=(Window,DedicatedWorker,SharedWorker), SecureContext]
namespace lp2p {
  ReadableStream makeDiscoverable(optional LP2PMakeDiscoverableOptions options = {});
  Promise<LP2PQuicTransport> connect(optional LP2PConnectOptions options = {});
};

dictionary LP2PMakeDiscoverableOptions : LP2PQuicTransportListenerInit {
  DOMString nickname;
  sequence<USVString> allowedOrigins = [];
};

dictionary LP2PConnectOptions : LP2PQuicTransportInit {
  DOMString nickname;
  AbortSignal signal;
};

lp2p.makeDiscoverable = options => {
  const receiver = new LP2PReceiver(options), listeners = new Set();
  let controller;
  const stream = new ReadableStream({ start: c => { controller = c; },
    cancel: () => { receiver.stop(); listeners.forEach(l => l.close()); } });
  receiver.onconnection = async ({ connection }) => {
    const listener = new LP2PQuicTransportListener(connection, options);
    listeners.add(listener);
    for await (const transport of listener.incomingTransports) controller.enqueue(transport);
  };
  receiver.start().catch(e => controller.error(e));
  return stream;
};

lp2p.connect = async options => {
  const connection = await new LP2PRequest(options).start(options);
  const transport = new LP2PQuicTransport(connection, options);
  try { await transport.ready; } catch (e) { connection.close(); throw e; }
  return transport;
};

// Peer A
for await (const transport of lp2p.makeDiscoverable({ nickname: "Peer A" })) {
    const stream = await transport.createBidirectionalStream();
}

// Peer B
const transport = await lp2p.connect({ nickname: "Peer B" });
const channel = transport.connection.createDataChannel("chat");

13. Document and worker lifecycle

When a Window’s associated Document stops being fully active, for example because it is unloaded or its frame is removed, or when a WorkerGlobalScope’s closing flag is set, the user agent must run these steps given that global object global:

1. For each LP2PReceiver whose relevant global object is global, stop it.

2. For each LP2PRequest whose relevant global object is global and whose [[StartPromise]] is pending, run its [[Abort]] given an "AbortError" DOMException. This takes down its user interface and closes the session being set up.

3. For each LP2PConnection whose relevant global object is global, close it.

Decide whether a document with receivers or connections may enter the back/forward cache instead, and what happens to them there.

14. Security and privacy considerations

Three guarantees are independent of each other: peer authentication, that a peer is the device the user paired with or confirmed (§ 4.5 Peer authentication); origin isolation, that in each browser a session is exposed only to the origin the user granted it to (§ 4.6 Peer grant, § 4.3 Peer advertisement); and application authorization, which is for the application to decide. None implies another. Authenticating a peer, or accepting its asserted requesting origin, must never implicitly grant any other capability, such as access to files, the network, storage or permissions.

Note: An application that needs proof of the remote origin can bind credentials its own origin issued to the session, with exportKeyingMaterial() on an LP2PQuicTransport, see export keying material. Once provisioned, this works offline. It proves that the origin issued the credential, not what runtime holds it on the other side.

14.1. Hardening before authentication

Before authentication, a user agent handles traffic from any device on the local communication medium. Implementations parse it as untrusted input and bound what it can cost: limits on connections and handshakes, timeouts, resource limits against denial of service, and isolation of the implementation from the rest of the user agent.

Treat hardening before authentication in more detail.

14.2. Transport bindings

14.3. Personally identifiable information

No information is exposed to the origin during service discovery. No IP information is exposed to an origin. This is fully managed by the user agent.

Refine the peer attributes exposed to origins. [WICG/local-peer-to-peer Issue #15]

14.4. User interface guidelines

When the user is asked to grant permission to connect to a peer, the user agent should make it clear what origin the request is coming from.

Define peer filtering to give the user additional context. [WICG/local-peer-to-peer Issue #15]

14.5. Authentication and locality

Peers authenticate each other out of band, usually by a trust ceremony in which the user takes part on one or both devices. Other means, such as a key provisioned in advance, could be defined later.

This specification does not require or rely on physical proximity. "Local" describes the envisioned use cases and the local communication medium, not a security guarantee: a peer can be further away than the user expects, for example on a large or misconfigured network or behind an intermediary, and a transport binding need not verify where it is.

So a peer, including a headless device, must not authorize anything because a request arrives over the local communication medium, or because of the requesting origin it asserts. It authorizes only peers it authenticated, and an application only with credentials that its origin issued, bound to the session with export keying material. This differs from protocols such as UPnP, where being on the network is the authorization.

14.6. Protecting users

The user is asked only what they can judge: which device to use, and which site may use it. The user agent does not hand the user security decisions it can make itself. In particular:

• start() and start() require transient activation, so that a page cannot prompt without a user action.

• Trusted user interface clearly distinguishes strings chosen by script or asserted by a peer, such as an nickname or an unverified display name, from those the user agent verified, such as an origin or a display name obtained on an authenticated session. It bounds their length and never presents them as instructions.

• User agents limit repeated prompts, for example by rate-limiting grant prompts per peer and per origin, remembering a decline for a while, and timing out incoming sessions that wait for a prompt.

• The user agent shows an indicator while it advertises and while a session is open. The prompt to advertise says that every device on the local communication medium can see the nickname.

Note: These are principles. How the user interface meets them is not specified further.

14.7. Impact on same-origin policy

This document extends the Web platform with the ability to set up real-time, direct communication between browsers and other devices, including other browsers, within a local communication medium.

This means that data and media can be shared between applications running in different browsers, or between an application running in the browser and another user agent that is not a browser such as a headless service provided by a smart TV or smart fridge. This extends the usual barriers in the Web’s security model that prevents sending data between entities with different origins.

To limit this, a session is only delivered to an LP2PReceiver of the same origin as its requesting origin, unless the receiver opts in to other origins, or with "*" to any requester, with allowedOrigins. The requesting origin is asserted by the peer’s user agent, so a peer can claim any origin. Such a peer is authenticated: the user paired with it in a trust ceremony, or a vouching party they trust vouches for it and they confirmed it, although they may never have paired with it. Authentication identifies the device, not its intent or the origin of the page using it.

14.8. Device Access

The Local Peer-to-Peer API requires user permission for a page to access any peers. The API uses purpose-fit protocols for data communication. It cannot be used to connect to raw sockets or unknowing HTTP servers. As in start(), the user first picks a peer in acquire a local peer grant; the session with it is then authenticated, with a trust ceremony if needed, and accepted by the peer; only then is the grant recorded with grant a peer.

14.9. Persistent State

14.10. Secure Contexts

15. Binding to the Open Screen Network Protocol

This section defines a transport binding to the Open Screen Network Protocol (OSP). In this binding, a peer is an OSP agent and a Local Peer-to-Peer session is an authenticated QUIC connection between two agents. Each Local Peer-to-Peer session has its own QUIC connection, even with the same agent, so that sessions are not shared between origins.

To discover metadata of an agent, the user agent follows Open Screen Network Protocol transport and metadata discovery.

The concepts and operations of § 6 Transport abstraction map onto OSP as follows:

Define how a data channel is closed.

Part of these operations are defined below as protocol extensions to the Open Screen Network Protocol.

15.1. Advertisement extension

An agent advertises one DNS-SD service instance, however many advertisements it has. Start advertising adds an advertisement with an advertisement ID of 16 bytes from a cryptographically secure random number generator, and starts advertising the service instance if it is the first. Stop advertising removes the advertisement, and stops advertising the service instance after the last one. Whenever its set of advertisements changes, the agent increases its metadata version (mv).

During discover metadata, after the agent-info-response, the listening agent sends an lp2p-advertisements-request message on a new bidirectional QUIC stream. The advertising agent answers on the same stream with an lp2p-advertisements-response message that lists, for each of its advertisements, its advertisement ID and nickname. Discover peers reports each of them as an advertisement of that agent.

Like agent-info, the listing is sent before authentication, to any agent that can reach the advertising agent. It reveals the number of advertisements, their nicknames and their advertisement IDs; it does not reveal origins. The advertisement IDs do not link one advertisement to another, but the agent fingerprint links them all.

The agent fingerprint in the mDNS TXT record, and the agent certificate that OSP presents on every QUIC connection, including metadata connections, identify the agent before authentication, across advertisements and networks. The nicknames in the listing are also sent before authentication. This binding does not fix either.

15.2. Session extension

To establish a session with an agent given an origin, the client opens a new QUIC connection to the agent, as described in transport. Both agents send auth-capabilities when the connection starts, as in OSP, so that both know which agent presents the PSK; this message does not start authentication. Only the client starts authentication, although OSP otherwise has an agent initiate authentication with an agent it has not verified.

When the client is the PSK consumer, it starts authentication with psk-needs-presentation. As written, OSP requires that message to carry pA, which needs the PSK the presenter has not created yet. This binding assumes OSP is fixed so that the message carries no public-value, and the presenter then starts the presenter-initiated flow.

This binding conveys the requesting origin only after authentication:

• Once it has received the agent’s agent-info-response, by discover metadata on that connection, the client starts authentication if it has not verified the server’s agent certificate.

• Once it has verified it, the client sends an lp2p-session-request message on a new bidirectional QUIC stream.

• A server that has not verified the client’s agent certificate answers with a provisional lp2p-session-response with the result authentication-required, without looking at the requesting-origin or the advertisement-id, and the client then starts authentication. The server sends no authentication message other than auth-capabilities before the client does.

• Once it has verified the client’s agent certificate, the server reports the connection as an incoming session for the advertisement whose advertisement ID is the advertisement-id, with the requesting-origin as its requesting origin. If it has no such advertisement, it refuses the session.

So the requesting-origin and advertisement-id are only sent to a verified server, and the server’s answer about it only reaches a verified client. Agents that have verified each other run no trust ceremony.

The lp2p-session-request contains:

requesting-origin

The ASCII serialization of the origin, or absent if the requesting origin is null. The server uses null if it is absent, and otherwise the origin of the result of running the URL parser on this value, or an opaque origin if parsing fails.

advertisement-id

The advertisement ID of the advertisement the client establishes the session with.

A client sends lp2p-session-request only to an agent whose capabilities are not empty, and only once per QUIC connection. A server that receives a second one closes the connection.

Authentication verifies the agent certificate that each agent presented in the TLS handshake of the QUIC connection that carries the lp2p-session-request: SPAKE2 uses the fingerprints of those certificates, and a certificate verified earlier is bound by the handshake itself. So the requesting-origin and advertisement-id are bound to the Local Peer-to-Peer session.

The server answers on the same stream with an lp2p-session-response message, containing:

result

authentication-required, provisional, as above; a final result follows on the same stream. success if the server accepts the session, or permanent-error if it refuses it. The server sends either only once it has verified the client’s agent certificate. After a refusal, the client ends its side of the stream, and the server closes the QUIC connection once it has, or after an implementation-defined timeout, so that the response is not lost.

The client treats the session as accepted once it has received success and has also verified the server’s agent certificate. Both agents then end their side of the stream.

The server does not send messages of the other extensions in this section on the connection before it has sent success, and the client not before it treats the session as accepted. The server may open data channels and WebTransport sessions right after sending success; the client holds streams that arrive before it treats the session as accepted until it does, and discards them if the session is not. To close a session, an agent closes the QUIC connection.

15.3. Data channel extension

In order to signal support for this protocol extension, the agent should include the data-channels agent-capability as part of the agent-info-response message exchanged during discover metadata. An agent does not send data-channel-open-request to an agent whose capabilities lack data channels.

To open a data channel, an agent may send a data-channel-open-request message on a new QUIC stream. The Local Peer-to-Peer session must be authenticated. The message must contain the following values:

channel-id

An ID number between 0 and 65,534 which uniquely identifies the data channel. When the binding chooses the id, the client uses an even number and the server an odd number. The value 65,535 is reserved, as for RTCDataChannel; id is an unsigned short for parity with id, but cannot take that value.

label

a string that contains a name describing the data channel. These labels are not required to be unique.

protocol

a string containing the name of the subprotocol in use. If no protocol was specified when the data channel was created, then this property’s value is the empty string ("").

The receiving agent reports the data-channel-open-request as an incoming data channel. When the receiver receives the data-channel-open-request, it should send back a data-channel-open-response message. The response must include the following:

result

a code indicating success or failure, and the reason for the failure. If the user agent refuses the incoming data channel, the result indicates failure.

If the data-channel-open-response message indicates success, the data channel is considered open. Agents can now send data on a channel by sending data-frame messages (type key 24) on the same QUIC stream the data channel was opened. The message must include the following keys; the other keys of data-frame (1, 2, 3 and 5) are unused, should not be sent, and must be ignored by the receiving agent:

encoding-id

Determines the encoding of the data being sent. The values are specified as data-channel-encoding-id, instead of referencing a data encoding offer: 0: Blob; 1: String; 2: ArrayBuffer.

payload

The binary representation of the data being sent.

A text message is sent with String; a binary message with Blob or ArrayBuffer. The receiving agent reports each data-frame as a received message, which is text if its encoding-id is String and binary otherwise.

15.4. WebTransport extension

The protocol extension to send data on a channel provides an ergonomic way to send simple messages. An agent can open a WebTransport session for communication that requires low overhead and more granular streams control.

An agent that supports this extension includes the quic-transport agent-capability in its agent-info-response, obtained by discover metadata, and must support QUIC DATAGRAM frames [RFC9221] on each connection that carries WebTransport sessions, so that its sessions are "supports-unreliable". An agent must not send the messages of this extension to an agent whose capabilities lack WebTransport, since an unknown type key closes the whole connection; open a WebTransport session fails instead. The capability describes the agent, not an origin: whether a page takes a session is answered by data-transport-start-response.

A WebTransport session is carried either on the QUIC connection of its Local Peer-to-Peer session, next to the other streams of that connection, or on a dedicated connection. Either agent can open a session on the QUIC connection of the Local Peer-to-Peer session; only the client opens a dedicated connection. So both agents can open a WebTransport session, as § 6.1 Peers and sessions requires.

15.4.1. Sessions

To open a WebTransport session, an agent opens a bidirectional QUIC stream, the session’s control stream, and sends a data-transport-start-request message on it, containing:

exchange-id

A number below 2⁶² that identifies the session within its Local Peer-to-Peer session, across that session’s QUIC connection and dedicated connections. The client uses even numbers and the server odd numbers, and neither reuses one.

session-binding

Only on a dedicated connection, see § 15.4.5 Dedicated connections.

The other agent reports an incoming WebTransport session. On the same stream it answers with a data-transport-start-response message, whose result is success if the session is accepted. Otherwise, it sends permanent-error and ends the stream with FIN; the session never opens. The opening agent does not open streams or send datagrams for the session before it receives success, and abandons a session it has had no response for by resetting the control stream.

15.4.2. Streams and datagrams

Each WebTransport stream is a QUIC stream with the same directionality, opened on the connection that carries the session. Its first message, sent by the agent that opened it, is a data-transport-stream message with the session’s exchange-id. The WebTransport stream’s data follows right after it, the other direction of a bidirectional stream carries only data, and FIN ends the stream. No response is sent.

A WebTransport datagram is a QUIC DATAGRAM frame whose payload is the session’s exchange-id, encoded as a QUIC variable-length integer [RFC9000], followed by the datagram. Datagrams for a session that is not open are dropped.

A WebTransport stream is reset or stopped with RESET_STREAM or STOP_SENDING. The QUIC application error code is the WebTransport stream error code, from 0 to 2³²−1. Codes from 2³² are reserved for this binding:

session-gone (2³²)

The stream’s session is closed or unknown. It is reported to script without a stream error code.

An unknown code from 2³² is treated as session-gone. An agent may hold, for a short time, a stream for a session that is not yet open, such as one the accepting agent opened right after sending success. Otherwise it refuses the stream with STOP_SENDING, and for a bidirectional stream also RESET_STREAM, with session-gone. A stream reset before its first message arrived is discarded.

15.4.3. Close and drain

To close a WebTransport session, an agent sends a data-transport-close message on the control stream and then ends the stream with FIN. It contains:

close-code

The close code, from 0 to 2³²−1.

reason

The reason, UTF-8 encoded, at most 1,024 bytes.

An agent that receives data-transport-close or a FIN on the control stream ends its side of it too. Both agents then reset and stop all streams of the session with session-gone. A control stream that ends with FIN without a data-transport-close closes the session with code 0 and an empty reason. A control stream that is reset, or a connection that closes, closes the session abruptly. So an agent that sent data-transport-close closes the QUIC connection only once the peer has ended its side of the control stream, or after an implementation-defined timeout, so that the message is not lost.

To drain a WebTransport session, an agent sends a data-transport-drain message on the control stream. An agent may do so when it intends to close the session soon.

15.4.4. Keying material exporters

To export keying material from a WebTransport session, an agent uses the TLS exporter of the QUIC connection that carries the session, with the label "EXPORTER-WebTransport" and, as context, the WebTransport Exporter Context of WebTransport over HTTP/3, Section 4.8, with the exchange-id as its session ID.

15.4.5. Dedicated connections

The client may carry a WebTransport session on a dedicated connection instead, for example to give it its own congestion control. It opens a new QUIC connection to the agent with the ALPN token "q2q" and the same agent certificate as its Local Peer-to-Peer session. The client closes the connection unless the server’s agent certificate has the agent fingerprint of the peer of that session. The server closes it unless the client’s agent certificate has the fingerprint of the peer of one of its Local Peer-to-Peer sessions.

Each data-transport-start-request on a dedicated connection contains a session-binding: 32 bytes from the TLS exporter of the QUIC connection of the Local Peer-to-Peer session, with the label "EXPORTER-LP2P-q2q" and an empty context. The first one binds the connection to the Local Peer-to-Peer session whose exporter yields the same bytes. The server closes the connection if there is none, or if a later request carries a different session-binding.

Only the client opens sessions on a dedicated connection, and only the messages of this extension are sent on it, without agent-info or authentication messages. Everything else in this section applies unchanged. The client closes the connection when its last session closes, or when the Local Peer-to-Peer session closes.

Appendix A: OSP Extension Messages

The following messages are defined according to and as an extension to the Open Screen Network Protocol Messages. The agent-capability, data-frame, request, response and result types are defined in the Open Screen Application Protocol Messages.

Note: The type keys and capability IDs for these extensions are not officially registered yet. They will be registered as this specification matures.

agent-capability /= &(
  data-channels: 1100
  quic-transport: 1200
)

data-channel-encoding-id = &(
  encoding-id-blob: 0
  encoding-id-string: 1
  encoding-id-array-buffer: 2
)

; data-frame (type key 24) is the Open Screen Application Protocol message;
; only its encoding-id (0) and payload (4) keys are used.

; type key 1110
lp2p-session-request = {
  request
  ? 1: text ; requesting-origin
  2: advertisement-id ; advertisement-id
}

; type key 1111
lp2p-session-response = {
  response
  1: lp2p-session-result ; result
}

lp2p-session-result = &(
  result,
  authentication-required: 1110
)

; type key 1112
lp2p-advertisements-request = {
  request
}

; type key 1113
lp2p-advertisements-response = {
  response
  1: [* lp2p-advertisement] ; advertisements
}

lp2p-advertisement = {
  0: advertisement-id ; advertisement-id
  1: text ; nickname
}

advertisement-id = bytes .size 16

; type key 1101
data-channel-open-request = {
  request
  1: uint ; channel-id
  2: text ; label
  3: text ; protocol
}

; type key 1102
data-channel-open-response = {
  response
  1: &result ; result
}

; type key 1201
data-transport-start-request = {
  request
  1: exchange-id ; exchange-id
  ? 2: bytes .size 32 ; session-binding
}

; type key 1202
data-transport-start-response = {
  response
  1: &result ; result
}

; type key 1203
data-transport-stream = {
  1: exchange-id ; exchange-id
}

exchange-id = uint .lt 4611686018427387904 ; below 2^62

; type key 1204 is reserved.

; type key 1205
data-transport-close = {
  0: uint .size 4 ; close-code
  1: text .size (0..1024) ; reason
}

; type key 1206
data-transport-drain = {
}