Native Peek-to-Peek API Draft Group Group Checklist

Demonstrate: This specification is below difficult vogue and therefore incomplete. When you’re attempting to search out an outline of the proposal, please discuss to the Explainer.

1. Introduction

This section is non-normative.

The Native Peek-to-Peek API targets to give browsers easy learn the technique to insist at the moment, with out the abet of a server within the guts. It is miles designed to enable this verbal exchange inside the confines of a local verbal exchange medium.

Many in type Web safety measures rely on the presence of naming, signaling and certificates authorities. Native utilize-cases the attach these authorities are no longer readily available agree with started lagging within the abet of in person ride or are no longer supported altogether. The Native Peek-to-Peek API targets to bring abet top quality strengthen for local verbal exchange utilize-cases while working inside the same strict person-friendliness, safety and privateness requirements.

Examples of doable makes utilize of of this API encompass: Collaboration instruments that work at some stage in an web outage or emergency eventualities, connecting to your NAS, your dwelling safety system, your robotic assistant doing the dishes or your GPU farm within the basement that’s running your personalized virtual assistant. Thought also Use Conditions.

This specification targets to strike a stability between making a resounding fresh building block for builders and offering a seamless, proper and privateness conserving ride for browser customers. As an instance: while the API doesn’t provide uncooked socket get entry to, it does goal to give builders the pliability to innovate on top by offering a continual, two-manner verbal exchange channel with dinky overhead.

The API is designed to be backed by an authenticated, streams-based completely completely transport. As a dedication to an delivery requirements-based completely completely implementation route, this specification describes how the API will also be implemented on top of the Birth Conceal veil Protocol. While no longer described here, the API is anticipated to be implementable on top of deal of transports when technically most likely.

2. Terminology

The term local verbal exchange medium refers to a verbal exchange medium that offers a neighborhood, order verbal exchange channel between the communicating units. Right here’s a purposefully huge term that covers any medium that can also be ancient to set a an authenticated, streams-based completely completely transport between the units. Examples could perhaps well encompass nonetheless are no longer puny to: a wired or wireless local condominium network, a Thread network, Bluetooth Low Vitality or Wi-Fi Tell. This spec will no longer mandate which underlying applied sciences must be supported.

The term local verbal exchange refers to records verbal exchange over the local verbal exchange medium.

The term verbal exchange medium topology refers to the composition of the local verbal exchange medium that can perhaps well encompass sensitive info corresponding to IP or deal of tackle info or the sequence of units connected to the medium.

3. Permission Policy Integration

The Native Peek-to-Peek API defines a policy-controlled just identified by the token “local-uncover about-to-uncover about”. Its default allowlist is "self".

Workers (devoted and shared) adhere to the permission policy reputation by their proudly owning file(s):

• Devoted workers will also be constituted of deal of workers, in which case the permission policy of the principle proudly owning file (in case of a devoted worker) or proudly owning documents (in case of a shared worker) up the proprietor chain could be ancient.
• Shared workers customarily agree with loads of proudly owning documents as they’ll even be bought by deal of documents with the same starting attach. On this case, all proudly owning documents must be allowed to utilize the policy-controlled just outlined by this specification.

Demonstrate: There used to be discussion on allowing surroundings permission policy at the moment on a worker on advent, in which case that can perhaps well wish to be consulted as successfully.

The default allowlist of "self" enables utilization in same-starting attach nested frames nonetheless prevents third-occasion speak material from the utilize of the just. Third-occasion speak material utilization will also be selectively enabled by adding allow="local-uncover about-to-uncover about" attribute to the physique container part:

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

Alternatively, the Native Peek-to-Peek API will also be disabled completely by specifying the permissions policy in a HTTP response header:

Permissions-Policy:  local-uncover about-to-uncover about=()

Thought [PERMISSIONS-POLICY] for additional minute print.

4. Peek Management

Demonstrate: This section and its subsections utilize RFC 2119 terminology in a relaxed manner. These sections could be transformed into successfully-outlined algorithmic normative prose told by additional implementation ride. For now, this relaxed description greater enables for immediate prototyping.

The person agent is responsible of managing friends.

A uncover about is an equal participant within the local verbal exchange. These nodes can be in contact with out the necessity for a central coordination by a server.

A person agent has an connected local uncover about-to-uncover about manager responsible of managing friends. Its responsibility is to delivery local uncover about discovery, set local uncover about connections and accomplish a neighborhood uncover about grant on a per-starting attach foundation. Right here’s performed to lead determined of disclosing info about the verbal exchange medium topology.

4.1. Identified friends

The person agent could perhaps well collected tackle a list of friends that it has info of.

The local uncover about-to-uncover about manager has an connected identified friends design, an ordered design of identified friends. Each identified uncover about is a uncover about that has an connected authentication impart and uncover about grant impart. The person agent retains monitor of the authentication impart per uncover about and the uncover about grant impart per uncover about, per starting attach. Unless endured, both the states are in the initiating faux.

Demonstrate: The uncover about grant impart is starting attach-stage while the authentication impart is uncover about-stage. The rationale is to no longer require the person to endure authentication loads of cases between the same friends. This invent could perhaps well commerce told by safety and privateness issues.

Thought also connected [Issue #wicg/local-peer-to-peer#24]

The person agent could perhaps well persist identified friends, their authentication states and/or uncover about grant states. If the person agent chooses to create so, it must create so in accordance with the Birth Conceal veil Protocol Persistent Affirm solutions. This kind of uncover about or its impart is supposed to be endured.

4.2. Peek advertisement

The person agent can get itself discoverable by promoting the utilize of the promote agent ability.

Demonstrate: The person agent must get the person’s explicit consent in issue to delivery promoting.

When promoting, the person agent must listen for incoming uncover about connections. In case a connection is obtained, the uncover about is added to the identified friends design. The person agent must never at the moment provide get entry to to the incoming uncover about connection to any starting attach. As a change, the person agent must urged to grant uncover about get entry to to the starting attach that initiated uncover about advertisement.

4.3. Peek discovery

The person agent can glance local friends the utilize of the glance agents ability.

When asked to delivery local uncover about discovery, the person agent discovers local friends the utilize of the glance agents ability.

If a uncover about is chanced on, the person agent could perhaps well collected add it to the identified friends design. The person agent must by no draw issue the fleshy result of uncover about discovery with an starting attach. As a change, the person agent must accomplish a neighborhood uncover about grant to grant get entry to to a uncover about for the starting attach that initiated the uncover about request.

4.4. Peek authentication

The person agent can originate authentication with a uncover about the utilize of the authenticate an agent ability.

When asked to authenticate a neighborhood uncover about, the person agent must originate authentication with a neighborhood uncover about the utilize of the authenticate an agent ability. The uncover about’s authentication impart must be reputation to lawful if authentication succeeds, otherwise faux.

A uncover about is supposed to be authenticated when its authentication impart is lawful.

4.5. Peek grant

The person agent, with the person’s consent, must accomplish a neighborhood uncover about grant for an starting attach to get get entry to to a uncover about.

Demonstrate: The person agent must get the person’s explicit consent in issue to grant an starting attach get entry to to a uncover about. For enhanced privateness protection, the person agent must provide technique to dismiss any connected person interface and this motion must never be detectable by script or agree with script-observable facet-effects. The person interface could perhaps well provide technique to revoke the grant or to get the grant endured.

When asked to accomplish a neighborhood uncover about grant, the person agent displays the identified friends to the person by its native person interface. When the person selects a uncover about from the person interface, the person agent must take a look at the selected uncover about is authenticated, and bustle the authenticate a neighborhood uncover about algorithm otherwise, and reputation the uncover about grant impart in step with the person’s explicit different.

5. Protocol concepts

When asked to set local uncover about connection, the person agent …

A Native Peek-to-Peek session represents an authenticated QUIC connection as outlined in Birth Conceal veil Protocol or OSP.

A Native Peek-to-Peek session has the next capabilities:

Piece of these capabilities are outlined below as protocol extensions to the Birth Conceal veil Protocol.

5.1. Recordsdata channel extension

In issue to signal strengthen for this protocol extension, the agent could perhaps well collected encompass the records-channels agent-ability as section of the agent-info-response message exchanged at some stage in glance metadata.

To delivery an info channel an agent could perhaps well ship a records-channel-delivery-request message on a fresh QUIC movement. The Native Peek-to-Peek session must be authenticated. The message must absorb the next values:

channel-identification

An ID quantity (between 0 and 65,534) which uniquely identifies the records channel. Must no longer be empty.

stamp

a string that features a popularity describing the records channel. These labels are no longer required to be outlandish.

protocol

a string containing the name of the subprotocol in utilize. If no protocol used to be specified when the records channel used to be created, then this property’s worth is the empty string (“”).

When the receiver receives the records-channel-delivery-request, it can perhaps well collected ship abet a records-channel-delivery-response message. The response must encompass the next:

result

a code indicating success or failure, and the explanation within the abet of the failure.

If the records-channel-delivery-response message indicates success, the records channel is believed to be delivery. Agents can now ship records on a channel by sending records-physique messages on the same QUIC movement the records channel used to be opened. The message must encompass the next:

encoding-identification

Determines the encoding of the records being sent. The values are specified as records-channel-encoding-identification:
0: Blob;
1: String;
2: ArrayBuffer.

payload

The binary illustration of the records being sent.

5.2. WebTransport extension

The protocol extension to ship records on a channel gives an ergonomic manner to ship easy messages. An agent can delivery a WebTransport session for verbal exchange that requires low overhead and additional granular streams management.

In issue to signal strengthen for this protocol extension, the agent could perhaps well collected encompass the immediate-transport agent-ability as section of the agent-info-response message exchanged at some stage in glance metadata.

An agent can delivery a WebTransport session by dialing a fresh QUIC connection the utilize of the agent certificates established at some stage in authenticate an agent. At some level of connection establishment, the ALPN token “q2q” must be ancient within the TLS handshake.

The capabilities of the Native WebTransport session are outlined in [webtransport].

Demonstrate: The WebTransport-over-QUIC protocol is yet to be outlined. Potentially excited by earlier work corresponding to draft-vvv-webtransport-quic.

[Exposed=(Window,Worker), SecureContext]
interface LP2PReceiver : EventTarget {
  constructor(non-mandatory LP2PReceiverOptions alternatives = {});
  attribute EventHandler onconnection;
  Promise<undefined> delivery();
};

[Exposed=(Window,Worker), SecureContext]
dictionary LP2PReceiverOptions {
    DOMString nickname;
};

[Exposed=(Window,Worker), SecureContext]
interface LP2PConnectionEvent : Match {
    constructor(DOMString kind, LP2PConnectionEventInit connectionEventInitDict);
    readonly attribute LP2PConnection connection;
};

dictionary LP2PConnectionEventInit : EventInit {
    required LP2PConnection connection;
};

const receiver = fresh LP2PReceiver({
    nickname:  "example-receiver",
});
receiver.onconnection = e => {
    console.log("Connection established!");
    const conn = e.connection;
};

// Blocks till permission is obtained.
stay up for receiver.delivery();

[Exposed=(Window,Worker), SecureContext]
interface LP2PRequest {
    constructor(non-mandatory LP2PRequestOptions alternatives = {});
    Promise<LP2PConnection> delivery();
};

[Exposed=(Window,Worker), SecureContext]
dictionary LP2PRequestOptions {
    DOMString nickname;
};

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

// Blocks till connection is obtained.
const conn = stay up for request.delivery();
console.log("Connection established!");

[Exposed=(Window,Worker), SecureContext]
interface LP2PConnection : EventTarget {
};

[Exposed=(Window,Worker), SecureContext]
partial interface LP2PQuicTransport {
  constructor(LP2PConnection connection,
              non-mandatory LP2PQuicTransportInit quicTransportDict = {});
};

const receiver = fresh LP2PReceiver({
    nickname:  "example-receiver",
});
receiver.onconnection = async e => {
    const conn = e.connection;
    
    const transport = fresh LP2PQuicTransport(conn);

    // Blocks till transport is prepared.
    stay up for transport.prepared;
};

// Blocks till permission is obtained.
stay up for receiver.delivery();

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

// Blocks till connection is obtained.
const conn = stay up for request.delivery();

const transport = fresh LP2PQuicTransport(conn);

// Blocks till transport is prepared.
stay up for transport.prepared;

[Exposed=(Window,Worker), SecureContext]
interface LP2PDataChannel : EventTarget {
  constructor(USVString stamp,
              non-mandatory LP2PDataChannelInit dataChannelDict = {});
  readonly attribute USVString stamp;
  readonly attribute USVString protocol;
  readonly attribute unsigned immediate? identification;
  attribute EventHandler onopen;
  attribute EventHandler onerror;
  attribute EventHandler onclosing;
  attribute EventHandler onclose;
  undefined shut();
  attribute EventHandler onmessage;
  attribute BinaryType binaryType;
  undefined ship((USVString or Blob or ArrayBuffer or ArrayBufferView) records);
};

[Exposed=(Window,Worker), SecureContext]
dictionary LP2PDataChannelInit {
  USVString protocol = "";
  [EnforceRange] unsigned immediate identification;
};

[Exposed=(Window,Worker), SecureContext]
partial interface LP2PConnection {
  LP2PDataChannel createDataChannel(USVString stamp,
                                    non-mandatory LP2PDataChannelInit dataChannelDict = {});
  attribute EventHandler ondatachannel;
};

[Exposed=(Window,Worker), SecureContext]
interface LP2PDataChannelEvent : Match {
  constructor(DOMString kind, LP2PDataChannelEventInit DataChannelEventInitDict);
  readonly attribute LP2PDataChannel channel;
};

dictionary LP2PDataChannelEventInit : EventInit {
    required LP2PDataChannel channel;
};

const receiver = fresh 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.records;
            console.log(`Receiver: Received message: ${message}`);
        };

        channel.ship("Appropriate day to you, requester!");
    };
};

stay up for receiver.delivery();

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

const conn = stay up for request.delivery();
console.log("Requester: Got a connection!");

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

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

    channel.ship("Appropriate day to you, receiver!");
};

[Exposed=(Window,Worker), SecureContext]
interface LP2PQuicTransport : WebTransport {
  constructor((LP2PRequest or LP2PReceiver) provide,
              non-mandatory LP2PQuicTransportInit quicTransportDict = {});
};

[Exposed=(Window,Worker), SecureContext]
dictionary LP2PQuicTransportInit {
};

[Exposed=(Window,Worker), SecureContext]
partial interface LP2PQuicTransportListener {
  constructor((LP2PRequest or LP2PReceiver) provide,
              non-mandatory LP2PQuicTransportListenerInit quicTransportListenerDict = {});
  readonly attribute Promise<undefined> prepared;
  /a ReadableStream of LP2PQuicTransport objects */
  readonly attribute ReadableStream incomingTransports;
};

[Exposed=(Window,Worker), SecureContext]
dictionary LP2PQuicTransportListenerInit {
};

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

const transport = fresh LP2PQuicTransport(request);

// Blocks till transport is prepared.
stay up for transport.prepared;

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

const listener = fresh LP2PQuicTransportListener(receiver);

for stay up for (const transport of listener.incomingTransports) {
  // Blocks till transport is prepared.
  stay up for transport.prepared;
}

12. Safety and privateness issues

12.1. Birth Conceal veil Protocol

The Native Peek-to-Peek API is supposed to be implementable on the Birth Conceal veil Protocol. The Safety and Privateness issues of the Birth Conceal veil Protocol must therefore be view to be when implementing this API.

12.2. For my half identifiable info

The uncover about attributes, such because the nickname and utility model, are supplied to give minimal context to a connected uncover about. This info will be ancient along with deal of information for fingerprinting the person. Nonetheless, this info is most attractive available to an starting attach after it has been authenticated and a person has given explicit consent to get the connection to the some distance flung uncover about.

No info is exposed to the starting attach at some stage in provider discovery. No IP info is exposed to an starting attach. Right here’s fully managed by the person agent.

Refine uncover about attributes, connected: [Issue #WICG/local-peer-to-peer#15]

12.3. Particular person interface guidelines

When the person is asked to grant permission to join to a uncover about, the person agent could perhaps well collected get it determined what starting attach the request is coming from.

Elaborate filtering to give extra context, connected: [Issue #WICG/local-peer-to-peer#15]

12.4. Impact on same-starting attach policy

This file extends the Web platform having the ability to reputation up proper-time, order verbal exchange between browsers and hundreds of units, including deal of browsers, inside a local verbal exchange medium.

This implies that records and media will also be shared between functions running in deal of browsers, or between an application running within the browser and one other person agent that’s no longer a browser corresponding to a headless provider supplied by a trim TV or trim fridge. This extends the common boundaries within the Web’s safety model that prevents sending records between entities with deal of origins.

12.5. Tool Win entry to

The Native Peek-to-Peek API requires person permission for a online page to get entry to any friends. The API makes utilize of motive-fit protocols for records verbal exchange. It could’t be ancient to join to uncooked sockets or unknowing HTTP servers. To boot, a person must accomplish a neighborhood uncover about grant by explicitly offering consenting for an starting attach to join to a uncover about. To boot, a person must authenticate a neighborhood uncover about earlier than utilize.

12.6. Persistent Affirm

The endured impart issues of the Birth Conceal veil Protocol must be adopted when implementing this API.

12.7. Obtain Contexts

The Native Peek-to-Peek API must most attractive be supplied in a proper context.

Appendix A: OSP Extension Messages

The next messages are outlined in step with and as an extension to the Birth Conceal veil Protocol Messages.

Demonstrate: The sort keys and ability IDs for these extensions are no longer officially registered yet. They’d be registered as this specification matures.

agent-ability = &(
  records-channels:  11OO
  immediate-transport:  12OO
)

records-channel-encoding-identification = &(
  encoding-identification-blob:  0
  encoding-identification-string:  1
  encoding-identification-array-buffer:  2
)

; kind key 24
records-physique = {
  0:  records-channel-encoding-identification ; encoding-identification
  4:  bytes ; payload
}

; kind key 1101
records-channel-delivery-request = {
  request
  1:  uint ; channel-identification
  2:  textual speak material ; stamp
  3:  textual speak material ; protocol
}

; kind key 1102
records-channel-delivery-response = {
  response
  1:  &result ; result
}