Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions EXPLAINER.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Build a generic Local Peer-to-Peer API and provide an arbitrary bidirectional co
- Means to send and receive data after connection to a peer device has been established
- Means to enable secure HTTPS connections on the local communication medium

As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [Open Screen Protocol](https://w3c.github.io/openscreenprotocol/). While not described here, the API is expected to be implementable on top of other transports when technically feasible.
As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [Open Screen Network Protocol](https://www.w3.org/TR/openscreen-network/). While not described here, the API is expected to be implementable on top of other transports when technically feasible.

### Non-goals

Expand Down Expand Up @@ -111,7 +111,7 @@ In summary, the following are the prerequisites:

## Solution Approach

The Local Peer-to-Peer API uses the to mutual authentication provided by the Open Screen Protocol to establish mutual TLS certificates between peers. These certificates serve as a trust anchor for secure [local communication](https://wicg.github.io/local-peer-to-peer/#local-communication). The Local Peer-to-Peer specification defines two uses of this new trust anchor:
The Local Peer-to-Peer API uses the to mutual authentication provided by the Open Screen Network Protocol to establish mutual TLS certificates between peers. These certificates serve as a trust anchor for secure [local communication](https://wicg.github.io/local-peer-to-peer/#local-communication). The Local Peer-to-Peer specification defines two uses of this new trust anchor:
Copy link

Copilot AI May 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There appears to be an extraneous word 'to' before 'mutual authentication'; consider removing it for clarity.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI May 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrase 'uses the to mutual authentication' appears to be a typo. Consider revising it to 'uses the mutual authentication' for clarity.

Copilot uses AI. Check for mistakes.

1. Enabling HTTPS on the local communication medium.
2. Enabling secure local communication using the `DataChannel` and `WebTransport` APIs.
Expand Down Expand Up @@ -272,7 +272,7 @@ A number of efforts exist in this area including the [TCP and UDP Socket API](ht

The Local Peer-to-Peer approach differs from previous work by putting the user-agent in control during device discovery and mutual authentication. This approach allows exposing bare minimal information about the device to an origin. The list of discovered devices is never shared with the origin and individual peer descriptors such as nickname are only shared with the origin after authentication and user consent. No [communication medium topology](https://wicg.github.io/local-peer-to-peer/#communication-medium-topology) information such as IP addresses is ever shared with an origin.

The following works are seen as precedent and guide the design of the Local Peer-to-Peer API: [Open Screen Protocol](https://www.w3.org/TR/openscreenprotocol/), [Presentation API](https://www.w3.org/TR/presentation-api/), [Remote Playback API](https://www.w3.org/TR/remote-playback/) [WebRTC](https://www.w3.org/TR/webrtc/), [ORTC (draft)](https://draft.ortc.org/), [WebTransport](https://www.w3.org/TR/webtransport/), [P2P WebTransport (draft)](https://w3c.github.io/p2p-webtransport/).
The following works are seen as precedent and guide the design of the Local Peer-to-Peer API: [Open Screen Network Protocol](https://www.w3.org/TR/openscreen-network/), [Presentation API](https://www.w3.org/TR/presentation-api/), [Remote Playback API](https://www.w3.org/TR/remote-playback/) [WebRTC](https://www.w3.org/TR/webrtc/), [ORTC (draft)](https://draft.ortc.org/), [WebTransport](https://www.w3.org/TR/webtransport/), [P2P WebTransport (draft)](https://w3c.github.io/p2p-webtransport/).

## References & Acknowledgements

Expand Down
42 changes: 23 additions & 19 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ Abstract: Local Peer-to-Peer is a Web platform API proposal for local communicat
Markup Shorthands: markdown yes, dfn yes, idl yes, markup yes
</pre>

<pre class="link-defaults">
spec:html; type:dfn; text:allowed to use
</pre>

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](https://github.com/WICG/local-peer-to-peer/blob/main/EXPLAINER.md).

Introduction {#intro}
Expand All @@ -30,7 +34,7 @@ Examples of potential uses of this API include: Collaboration tools that work du

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. As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [[!openscreenprotocol|Open Screen Protocol]]. While not described here, the API is expected to be implementable on top of other transports when technically feasible.
The API is designed to be backed by an authenticated, streams-based transport. As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [[!openscreen-network|Open Screen Network Protocol]]. While not described here, the API is expected to be implementable on top of other transports when technically feasible.

Terminology {#terminology}
======================================================
Expand Down Expand Up @@ -94,7 +98,7 @@ Note: The [=peer grant state=] is origin-level while the [=authentication state=

Issue(wicg/local-peer-to-peer#24): See also related

The user agent may persist known peers, their [=authentication states=] and/or [=peer grant states=]. If the user agent chooses to do so, it must do so in accordance with the [[!openscreenprotocol|Open Screen Protocol]] Persistent State rules. Such a peer or its state is said to be <dfn>persisted</dfn>.
The user agent may persist known peers, their [=authentication states=] and/or [=peer grant states=]. If the user agent chooses to do so, it must do so in accordance with the [[!openscreen-network|Open Screen Network Protocol]] [Persistent State rules](https://www.w3.org/TR/openscreen-network/#persistent-state). Such a peer or its state is said to be <dfn>persisted</dfn>.

Peer advertisement {#peer-advertisement}
----------------------------------------
Expand Down Expand Up @@ -137,7 +141,7 @@ Protocol concepts {#protocol-concepts}

When asked to <dfn>establish local peer connection</dfn>, the user agent ...

A <dfn for="protocol">Local Peer-to-Peer session</dfn> represents an authenticated [[!RFC9000|QUIC]] connection as defined in [[!openscreenprotocol|Open Screen Protocol]] or OSP.
A <dfn for="protocol">Local Peer-to-Peer session</dfn> represents an authenticated [[!RFC9000|QUIC]] connection as defined in [[!openscreen-network|Open Screen Network Protocol]] or OSP.

A [=Local Peer-to-Peer session=] has the following capabilities:

Expand All @@ -151,23 +155,23 @@ A [=Local Peer-to-Peer session=] has the following capabilities:
<tbody>
<tr>
<td><dfn>advertise agent</dfn>
<td>[[!openscreenprotocol]]
[discovery](https://www.w3.org/TR/openscreenprotocol/#discovery)
<td>[[!openscreen-network|Open Screen Network Protocol]]
[discovery](https://www.w3.org/TR/openscreen-network/#discovery)
</tr>
<tr>
<td><dfn>discover agents</dfn>
<td>[[!openscreenprotocol]]
[discovery](https://www.w3.org/TR/openscreenprotocol/#discovery)
<td>[[!openscreen-network|Open Screen Network Protocol]]
[discovery](https://www.w3.org/TR/openscreen-network/#discovery)
</tr>
<tr>
<td><dfn>discover metadata</dfn>
<td>[[!openscreenprotocol]]
[transport](https://www.w3.org/TR/openscreenprotocol/#transport)
<td>[[!openscreen-network|Open Screen Network Protocol]]
[transport](https://www.w3.org/TR/openscreen-network/#transport)
</tr>
<tr>
<td><dfn>authenticate an agent</dfn>
<td>[[!openscreenprotocol]]
[authentication](https://www.w3.org/TR/openscreenprotocol/#authentication)
<td>[[!openscreen-network|Open Screen Network Protocol]]
[authentication](https://www.w3.org/TR/openscreen-network/#authentication)
</tr>
<tr>
<td>[=open a data channel=]
Expand All @@ -184,12 +188,12 @@ A [=Local Peer-to-Peer session=] has the following capabilities:
</tbody>
</table>

Part of these capabilities are defined below as [protocol extensions](https://www.w3.org/TR/openscreenprotocol/#protocol-extensions) to the [[!openscreenprotocol|Open Screen Protocol]].
Part of these capabilities are defined below as [protocol extensions](https://www.w3.org/TR/openscreen-network/#protocol-extensions) to the [[!openscreen-network|Open Screen Network Protocol]].

Data channel extension {#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](https://www.w3.org/TR/openscreenprotocol/#agent-info-response) message exchanged during [=discover metadata=].
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](https://www.w3.org/TR/openscreen-network/#messages) message exchanged during [=discover metadata=].

To <dfn>open a data channel</dfn> an agent may send a [=data-channel-open-request=] message on a new [[!RFC9000|QUIC]] stream. The [=Local Peer-to-Peer session=] must be authenticated. The message must contain the following values:

Expand Down Expand Up @@ -223,7 +227,7 @@ WebTransport extension {#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.

In order to signal support for this protocol extension, the agent should include the [=quick-transport=] [=agent-capability=] as part of the [agent-info-response](https://www.w3.org/TR/openscreenprotocol/#agent-info-response) message exchanged during [=discover metadata=].
In order to signal support for this protocol extension, the agent should include the [=quick-transport=] [=agent-capability=] as part of the [agent-info-response](https://www.w3.org/TR/openscreen-network/#messages) message exchanged during [=discover metadata=].

An agent can <dfn>open a WebTransport session</dfn> by dialing a new [[!RFC9000|QUIC]] connection using the agent certificates established during [=authenticate an agent=]. During connection establishment, the ALPN token "q2q" must be used in the TLS handshake.

Expand All @@ -236,7 +240,7 @@ Note: The WebTransport-over-QUIC protocol is yet to be defined. Potentially cons
Local HTTPS {#local-https}
==========================

Authentication establishes a mutual trust anchor between peers on the [=local communication medium=]. This trust anchor can also be used to validate certificates used by HTTP servers on the [=local communication medium=]. An Open Screen Protocol agent certificate can be identified by the common name of its subject ending in "._openscreen._udp". When a user agent loads a webpage and finds an agent certificate in the certificate chain, it can use it as a trust anchor for authentication of the server. If the corresponding agent is not [=authenticated=], the user agent should prompt the user to authenticate the agent before proceeding with certificate validation.
Authentication establishes a mutual trust anchor between peers on the [=local communication medium=]. This trust anchor can also be used to validate certificates used by HTTP servers on the [=local communication medium=]. An Open Screen Network Protocol agent certificate can be identified by the common name of its subject ending in "._openscreen._udp". When a user agent loads a webpage and finds an agent certificate in the certificate chain, it can use it as a trust anchor for authentication of the server. If the corresponding agent is not [=authenticated=], the user agent should prompt the user to authenticate the agent before proceeding with certificate validation.

Endpoint discovery {#local-https-discovery}
-------------------------------------------
Expand Down Expand Up @@ -776,9 +780,9 @@ Refer to the [WebTransport examples](https://www.w3.org/TR/webtransport/#example
Security and privacy considerations {#security-and-privacy-considerations}
=========================================================================

Open Screen Protocol {#security-osp}
Open Screen Network Protocol {#security-osp}
------------------------------------
The Local Peer-to-Peer API is meant to be implementable on the [[!openscreenprotocol|Open Screen Protocol]]. The Security and Privacy considerations of the Open Screen Protocol must therefore be considered when implementing this API.
The Local Peer-to-Peer API is meant to be implementable on the [[!openscreen-network|Open Screen Network Protocol]]. The Security and Privacy considerations of the Open Screen Network Protocol must therefore be considered when implementing this API.

Personally identifiable information {#security-pii}
---------------------------------------------------
Expand Down Expand Up @@ -809,7 +813,7 @@ The Local Peer-to-Peer API requires user permission for a page to access any pee

Persistent State {#security-persistent-state}
---------------------------------------------
The persisted state considerations of the [[!openscreenprotocol|Open Screen Protocol]] must be followed when implementing this API.
The persisted state considerations of the [[!openscreen-network|Open Screen Network Protocol]] [Persistent State rules](https://www.w3.org/TR/openscreen-network/#persistent-state) must be followed when implementing this API.

Secure Contexts {#security-secure-context}
------------------------------------------
Expand All @@ -818,7 +822,7 @@ The Local Peer-to-Peer API must only be provided in a secure context.
Appendix A: OSP Extension Messages {#appendix-a}
================================================

The following messages are defined according to and as an extension to the [[!openscreenprotocol|Open Screen Protocol]] [Messages](https://www.w3.org/TR/openscreenprotocol/#appendix-a).
The following messages are defined according to and as an extension to the [[!openscreen-network|Open Screen Network Protocol]] [Messages](https://www.w3.org/TR/openscreen-network/#appendix-a).

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

Expand Down
4 changes: 2 additions & 2 deletions security-privacy-questionnaire.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
- A: By design no such information should be exposed.
7. Does this specification allow an origin to send data to the underlying
platform?
- A: The specification is meant to be implementable using the Open Screen Protocol, a cross platform protocol.
- A: The specification is meant to be implementable using the Open Screen Network Protocol, a cross platform protocol.
8. Do features in this specification enable access to device sensors?
- A: The specification doesn't allow direct access to device sensors.
9. Do features in this specification enable new script execution/loading
Expand All @@ -39,7 +39,7 @@
- A: A [Permission Policy Integration](https://wicg.github.io/local-peer-to-peer/#permission-policy-integration) has been defined.
14. How do the features in this specification work in the context of a browser’s
Private Browsing or Incognito mode?
- A: The [specification](https://www.w3.org/TR/openscreenprotocol/#private-browsing-mode) of the OpenScreen protocol are to be followed in this area.
- A: The [specification](https://www.w3.org/TR/openscreen-network/#private-browsing-mode) of the Open Screen Network Protocol are to be followed in this area.
15. Does this specification have both "Security Considerations" and "Privacy
Considerations" sections?
- A: Both Security and Privacy concerns have been considered.
Expand Down