Web10-npm NPM | npm.io

web10 DOCS | SDKs

web10 Home

web10 auth portal

web10 API page

Getting Started

SDK Installation (npm)

In your node application, run the following command.

npm -i web10-npm

Then, in your application you can import the package at the top.

import {wapiInit} from 'web10-npm'

SDK Installation (CDN Link)

wapi.js is the javascript file containing the web10 developers SDK. the file can be found at : https://unpkg.com/web10-npm/dist/wapi.js

<!-- Installing using CDN -->
<script src="https://unpkg.com/web10-npm/dist/wapi.js"></script>

SDK Initialization (JS)

in order to use the web10 SDK, the main SDK object needs to be initialized by the developer.

function	description
wapiInit(authUrl, appStores, rtcServer)	returns a wapi object registered to handle web10 authentication at the auth portal of the given authUrl. It registers the application to the provided list of app stores, and registers for P2P webrtc with the provided web10 webRTC server.

appStores and rtcServer are optional parameters, set respectively to appStores = "https://api.web10.app" and rtcServer = "rtc.web10.app" by default.

/* simplest way to initialize a wapi object registered for auth with auth.web10.app */
const wapi = wapiInit("https://auth.web10.app")

/*
* initializing a wapi object with the optional parameters.
*      appStores - A list of app stores to register the app with.
*      rtcServer - A domain name of a web10 webRTC server to use for P2P
*/
wapiInit(authUrl = "https://auth.web10.app", appStores=["https://api.web10.app"], rtcServer = "rtc.web10.app")

Authentication

SDK Functions

once the wapi object is initialized, it provides a variety of functionalities for managing authentication and credentials.

function	description
wapi.isSignedIn()	returns a boolean : whether the app is signed in.
wapi.signOut()	signs the app out.
wapi.openAuthPortal()	opens the registered web10 auth portal.
wapi.authListen(setAuth)	listens for the auth portal to send a login token, and triggers the inputted callback function setAuth
wapi.readToken()	reads the data fields of the web10token stored in the wapi object. if wapi isn't logged in and the token is null, wapi.readToken() returns null.
wapi.getTieredToken(site,target)	mints a token for a given site and web10server using the token stored in wapi. returns an axios promise with response data being the tokenas JWT string on success.

Anonymous Users

When not logged into web10 on a website with the wapi.js sdk, you can still utilize the web10 CRUD functionality. The api will register you as the 'anon' user a user with the name anon.

Hello World Demo

Below is an example of some html and javascript utilizing all of the above SDK functions to handle login for a simple hello world app. Demo Link

<html>
	<!-- index.html -->
    <head>
        <link rel="shortcut icon" href="#">
        <meta name="viewport" content="width=device-width" />
    </head>
    <body>
        <button id="authButton">
            log in
        </button>
        <p id="message">
            app not started
        </p>
    </body>
    <!-- Installing using CDN -->
    <script src="https://unpkg.com/web10-npm@1.0.5/dist/wapi.js" ></script>
    <script src="script.js"></script>
</html>

/* script.js */

//initialize a wapi object registered for auth with auth.web10.app
const wapi = wapiInit("https://auth.web10.app")

// make the auth portal open when the log in button is pressed 
authButton.onclick = wapi.openAuthPortal

// callback function that initializes the app on web10 login
function initApp(){
    // make the logout button handle logouts properly on login
    authButton.innerHTML = "log out";
    authButton.onclick = () => {
        wapi.signOut();
        window.location.reload();
    }
    // simple hello world app, saying hello to the user
    const t = wapi.readToken()
	message.innerHTML = `hello ${t["provider"]}/${t["username"]},<br>`    
}

// either initialize the app if logged in, wait for authentication to do so.
if (wapi.isSignedIn()) initApp()
else wapi.authListen(initApp)

Services

a web10 service is a managed MongoDB collection provided by a web10 provider

web10.app services are hosted at :

User Consent

users start new web10 services by accepting SIRs service initialization requests
users accept or deny changes to terms of service through SCRs service change requests
users can change their terms of service in the web10 authentication portal at any time.

SDK CRUD + Service Management Functions

function	description
wapi.SMROnReady(sirs,scrs)	adds an event listener that waits for the authentication service to send a ready signal. when the authentication service is ready, wapi sends a service modification request SMR. an SMR consists of list of service initialization requests SIRs and a list of service change requests SCRs
wapi.create(service,query,username,provider)	Runs a MongoDB create on the web10 service at provider/{username}/{service}, and returns the result as an axios promise.
wapi.read(service,query,username,provider)	Runs a MongoDB read on the web10 service at provider/{username}/{service}, and returns the result as an axios promise.
wapi.update(service,query,update,username,provider)	Runs a MongoDB update on the web10 service at provider/{username}/{service}, and returns the result as an axios promise.
wapi.delete(service,query,username,provider)	Runs a MongoDB delete on the web10 service at provider/{username}/{service}, and returns the result as an axios promise.

Additional Details about wapi.read(service,query,username,provider) for pagination.

// Additional Detail about wapi.read !!!
// In web10, keys of documents can't be started with a dollar sign. web10 read queries will ignore dollar signs in query keys, EXCEPT for $sort, $skip, and $limit, which are features built into web10 for pagination, explained below.

// wapi.read adds special parameters to the query parameter for pagination.
// $sort : {key : 1 or -1 } - lets you pass in 1 or -1 to sort output ascending or descending.
// $skip : integer - a number of documents to skip in the query, for simple offset pagination
// $limit : integer - a number of documents to return from the query.

//example: 
wapi.read("notes",{$skip:10,$limit:10})

Additional details about wapi.update(service, query, update, username, provider).

// Additional Detail about wapi.update !!!
wapi.update(service, query, update, username, provider) returns
{
        "matchedCount" : number of documents that matched the query
        "modifiedCount" : number of documents modified.
}
// This lets a web10 developer upsert via. calling wapi.update. If 0 documents are matched, they can follow up with a wapi.create query.

/* 
web10 adds an additional helpful parameter to the update argument, PULL. 
if set to true i.e. PULL:true, it pulls any null array values out of the arrays in web10 documents updated. 
PULL has unspecified behavior on documents holding numerically keyed dictionaries.
*/

Service Terms

Users have a service term record for each active service they actively host with web10.

field	description
service	the name of the web10 service
cross_origins	websites that users are allowed to make web10 requests to the service from.
whitelist	a list of users allowed to access the service
blacklist	a list of users not allowed to access the service. Overrides user listings on the whitelist.

{
    service : the name of the service 
    cross_origins : [website1, website2 website3] [regex for exact matching allowed]
    whitelist : [
        {
            user: the name of a web10 user [regex for exact matching allowed]
            provider : the name of a web10 provider [regex for exact matching allowed]
            create : true or false
            read : true or false
            update : true or false
            delete : true or false
            all : true or false
        }, ... 
	]
	blacklist : [ same as whitelist entries ...]
}

Subservices (Coming soon)

Subservices are developer definable services within a service. There properties are :

They can have only stricter rules than the services they are within.
The rules can never restrict access from the user who owns the service.
Developers do not need to get user consent to make subservices

Note App Demo

Below is an example of some html and javascript utilizing all of the above user owned service management functionality to make a basic notes app. Demo Link

<html>
<!-- index.html -->
<head>
    <link rel="shortcut icon" href="#">
    <meta name="viewport" content="width=device-width" />
</head>
<body>
    <button id="authButton">
        log in
    </button>
    <p id="message">
        app not started
    </p>
    <div>
        <textarea id="curr" placeholder="write a note here"></textarea>
        <button onclick="createNote(curr.value)">create note</button>
    </div>
    <div id="noteview"></div>
</body>
<script src="https://unpkg.com/web10-npm@1.0.5/dist/wapi.js"></script>
<script src="script.js"></script>
</html>

/* script.js */

//conventient failure messages
const Fs = ([cF, rF, uF, dF] = ["create", "read", "update", "delete"].map(
  (op) => `failed to ${op} note[s]`
));

/* wapi setup */
const wapi = wapiInit("https://auth.web10.app");
const sirs = [
  {
    service: "web10-docs-note-demo",
    cross_origins: ["docs.web10.app", "localhost", "docs.localhost"],
  },
];
wapi.SMROnReady(sirs, []);
authButton.onclick = wapi.openAuthPortal;

function initApp() {
  authButton.innerHTML = "log out";
  authButton.onclick = () => {
    wapi.signOut();
    window.location.reload();
  };
  const t = wapi.readToken();
  message.innerHTML = `hello ${t["provider"]}/${t["username"]},<br>`;
  readNotes();
}

if (wapi.isSignedIn()) initApp();
else wapi.authListen(initApp);

/* CRUD Calls */
function readNotes() {
  wapi
    .read("web10-docs-note-demo", {})
    .then((response) => displayNotes(response.data))
    .catch((error) => (message.innerHTML = `${rF} : ${error.response.data.detail}`));
}
function createNote(note) {
  wapi
    .create("web10-docs-note-demo", { note: note, date: String(new Date()) })
    .then(() => {
      readNotes();
      curr.value = "";
    })
    .catch(
      (error) => (message.innerHTML = `${cF} : ${error.response.data.detail}`)
    );
}
function updateNote(id) {
  const entry = String(document.getElementById(id).value);
  wapi
    .update("web10-docs-note-demo", { _id: id }, { $set: { note: entry } })
    .then(readNotes)
    .catch(
      (error) => (message.innerHTML = `${uF} : ${error.response.data.detail}`)
    );
}
function deleteNote(id) {
  wapi
    .delete("web10-docs-note-demo", { _id: id })
    .then(readNotes)
    .catch(
      (error) => (message.innerHTML = `${dF} : ${error.response.data.detail}`)
    );
}

/* display */
function displayNotes(data) {
  function contain(note) {
    return `<div>
                <p style="font-family:monospace;">${note.date}</p>
                <textarea id="${note._id}">${note.note}</textarea>
                <button onclick="updateNote('${note._id}')">Update</button>
                <button onclick="deleteNote('${note._id}')">Delete</button>
            </div>`;
  }
  noteview.innerHTML = data.map(contain).reverse().join(`<br>`);
}

devPay

Developers can accept web10 payment with web10 devPay.

function	description
wapi.checkout (seller, title, price,successUrl,cancelUrl)	Opens a subscription checkout portal for a customer.
wapi.verifySubscription (seller, title)	Verify that a customer is subscribed.
wapi.wapi.cancelSubscription (seller, title)	Cancel a customer subscription

Demo - web10 Mail App

Below is a demo mail app. It showcases:

service term regexing to allow all web10 users send you an email.
$.50/mo. web10 devPay subscription.
sending of web10 mail as an anon web10 user when not logged in.

Demo Link

<html>
<!-- index.html -->
<head>
    <link rel="shortcut icon" href="#">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.1/css/bulma.min.css" />
    <link rel="stylesheet" href="style.css" />
    <meta name="viewport" content="width=device-width" />
</head>
<body>
    <div class="main">
        <button id="authButton">
            log in
        </button>
        <p id="message">
            app not started
        </p>
        <div id="subscriptionStatus">awaiting subscription check</div>
        <br>
        <div>
            <div>
                <input class="" id="recipient" placeholder="recipient">
                <input class="" id="web10server" placeholder="web10server" value="api.web10.app">
            </div>
            <div>
                <textarea id="curr" placeholder="write message here"></textarea>
            </div>
            <div>
                <button onclick="createMail(curr.value,recipient.value,web10server.value)">create mail</button>
            </div>
        </div>
        <div id="mailview"></div>
    </div>
</body>
<script src="https://unpkg.com/web10-npm@1.0.5/dist/wapi.js"></script>
<script src="script.js"></script>
</html>

/* style.css */
div {
  margin-top: 5px;
}
input {
  margin-bottom: 3px;
}
textarea {
  width: 100%;
  height: 200px;
}

/* script.js */

//conventient failure messages
const Fs = ([cF, rF, uF, dF] = ["create", "read", "update", "delete"].map(
  (op) => `failed to ${op} mail[s]`
));

/* wapi setup */
const wapi = wapiInit("https://auth.web10.app");
const sirs = [
  {
    service: "web10-docs-mail-demo",
    cross_origins: ["docs.web10.app", "localhost", "docs.localhost"],
    whitelist: [{ username: ".*", provider: ".*", create: true }], //allows all users to write to you
  },
];
wapi.SMROnReady(sirs, []);
authButton.onclick = wapi.openAuthPortal;

/* web10 devPay */
const [seller, subscriptionTitle, price, url] = [
  "seller-web10-username",
  "mailer-premium",
  50,
  window.location.href,
];

/* message for current subscribers */
function displaySubscriberMessage() {
  subscriptionStatus.innerHTML = `subscribed! <button id="cancel"> cancel sub </button>`;
  cancel.onclick = () =>
    wapi
      .cancelSubscription(seller, subscriptionTitle)
      .then(() => window.location.reload())
      .catch((e) => {
        subscriptionStatus.innerHTML = `subscription cancellation failed...`;
      });
}

/* message for users that are not subscribed to onboard them */
function displayOnboardMessage() {
  subscriptionStatus.innerHTML = `not subscribed! <button id="checkout"> subscribe </button>`;
  checkout.onclick = () =>
    wapi.checkout(seller, subscriptionTitle, price, url, url).catch((e) => {
      message.innerHTML = e.response.data.detail;
    });
}

/* a front end weak subscription check [still lucrative!] */
function validSubscription(subscriptionData) {
  return (
    subscriptionData !== null &&
    parseInt(subscriptionData["price"]) === price &&
    subscriptionData["seller"] === seller &&
    subscriptionData["title"] === title
  );
}

/* The devpay functionality */
function devPay() {
  wapi
    .verifySubscription(seller, subscriptionTitle)
    .then((r) => {
      if (validSubscription(r["data"])) displaySubscriberMessage();
      else displayOnboardMessage();
    })
    .catch(
      (e) => (subscriptionStatus.innerHTML = `subscription check failed...`)
    );
}

function initApp() {
  authButton.innerHTML = "log out";
  authButton.onclick = () => {
    wapi.signOut();
    window.location.reload();
    devPay();
  };
  const t = wapi.readToken();
  message.innerHTML = `hello ${t["provider"]}/${t["username"]},<br>`;
  readMail();
  devPay();
}

if (wapi.isSignedIn()) initApp();
else wapi.authListen(initApp);

/* CRUD Calls */
function readMail() {
  wapi
    .read("web10-docs-mail-demo", {})
    .then((response) => displayMail(response.data))
    .catch((error) => (message.innerHTML = `${rF} : ${error}`));
}
function createMail(mail, user, provider) {
  const t = wapi.readToken();
  const sender = t===null ? "anon":t["username"]
  wapi
    .create(
      "web10-docs-mail-demo",
      {
        mail: mail,
        date: String(new Date()),
        provider: provider,
        username: sender,
      },
      user,
      provider
    )
    .then(() => {
      if (sender!=="anon") readMail();
      curr.value = "";
      message.innerHTML = "sent message";
    })
    .catch((error) => (message.innerHTML = `${cF} : ${error}`));
}
function deleteMail(id) {
  wapi
    .delete("web10-docs-mail-demo", { _id: id })
    .then(readMail)
    .catch(
      (error) => (message.innerHTML = `${dF} : ${error.response.data.detail}`)
    );
}

/* display */
function displayMail(data) {
  function contain(mail) {
    return `<div style="margin-top:40px;margin-left:10px">
                <p style="font-family:monospace;">${mail.date}</p>
                <p style="font-family:monospace;">${mail.provider}/${mail.username}</p>                
                <i id="${mail._id}">${mail.mail}</i>
                <button onclick="deleteMail('${mail._id}')">Delete</button>
            </div>`;
  }
  mailview.innerHTML = data.map(contain).reverse().join(`<br>`);
}

P2P (Via. PeerJS) (Coming soon)

web10 peer to peer functionality relies on the PeerJS library. web10 runs it's own webRTC server to keep web10 users secure when using the platform.

SDK Functions

Function	Description
wapi.initP2P(onInbound=null)	Initializes the client as a peer, and on recieving inbound connections saves the connections to wapi.inBound. and attaches an event listener that triggers the onInbound(conn,data) function to recieved inbound connections
wapi.P2P(provider, username, origin, metaData={}, label = "default")	Makes a P2P connection with another web10 peer.

Outbound/Inbound P2P

Connections that other web10 users make to you are stored in the wapi.inBound dictionary under their peer ID.

Connections that you make to other web10 users are stored in the wapi.outBound dictionary under their peer ID.

web10 Peer IDs

On web10, peer ids look like 'provider/username/origin/label'

provider is the web10 provider of a user of web10 P2P
username is the web10 username of a user of web10 P2P
origin is the origin of the site the user is using to make the web10 P2P connection
- when connecting to a mobile encryptor, origin is set to "mobile"
label is an extra string a developer can add to the peer id to handle single users being multipeer

P2P messaging demo (Coming soon)

see https://mail.web10.app

Encryption (Coming soon)

web10 does the following to make encryption is as secure as possible :

Implements SEPC256K1 encryption for digital signatures, diffie helman, and assymetric encryption
Has a mobile app client to store all of your web10 keys locally on your phone to keep the keys entirely secret.
Creates a P2P tunnel between your phone and web10 using devices to keep your web10 apps secure.