This page describes how an app logs a user in to their Nova account without ever seeing their password. It is complete: a developer, or a coding assistant, can build the login from this page alone, without reading Nova’s source code.

Summary#

  • The protocol is the OAuth 2.0 authorization code flow (RFC 6749) with PKCE (RFC 7636), used the way RFC 8252 prescribes for apps which run on the user’s own device.
  • There is no client secret, no refresh token and no expiry time in the response.
  • What the app gets in the end is an ordinary Nova API key. It sends the key as a Bearer token with every API request.
  • The key has only the permissions the app asked for, and the user can limit it to certain directories.

Everything on this page runs on the test cluster https://dev.nova.storage. Accounts on it are separate from the ones on nova.storage. Make the base URL a setting in your app: the production site will use the same paths on another host.

What Method URL
Authorization page (browser) GET https://dev.nova.storage/oauth/authorize
Token endpoint (app) POST https://dev.nova.storage/api/user/oauth/token
Everything else in the API https://dev.nova.storage/api/...

Registered apps#

An app has to be registered by Nova before it can use this. A request from an app which is not in this list, or with a redirect URI which does not match its registration, ends on an error page.

client_id Name the user sees Redirect URI
jevido-nova Jevido Nova App http://127.0.0.1:{port}/oauth/callback

The redirect URI is compared to the letter, except for the port:

  • The scheme is http and the host is 127.0.0.1. Not localhost, not [::1], not https.
  • {port} is any port number from 0 to 65535. The app picks a free one each time it logs in.
  • The path is exactly /oauth/callback. No trailing slash, no query string.

The flow#

1. Make the secrets#

Before every login the app makes two random values:

  • code_verifier: 43 to 128 characters from A-Z, a-z, 0-9, -, ., _ and ~. The simple way is 32 random bytes from a cryptographic random source, encoded as base64url without padding, which gives 43 characters.
  • state: any random string of up to 2000 characters. Make it the same way.

From the verifier it computes the challenge:

code_challenge = base64url_without_padding(sha256(ascii(code_verifier)))

The result is always 43 characters. To test your code: the verifier dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk has the challenge E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.

The app keeps the verifier and the state in memory until the login is done. It never puts the verifier in a URL.

2. Listen for the answer#

The app starts an HTTP server on 127.0.0.1, on any free port. Its redirect URI for this login is http://127.0.0.1:{port}/oauth/callback, with that port in it.

3. Send the user to the authorization page#

The app opens this URL in the default browser of the user. It must be the real browser, not a web view inside the app: the user is usually logged in to Nova there already, and they have to be able to see that the page is Nova’s.

https://dev.nova.storage/oauth/authorize
    ?response_type=code
    &client_id=jevido-nova
    &redirect_uri=http%3A%2F%2F127.0.0.1%3A41234%2Foauth%2Fcallback
    &scope=filesystem_read+filesystem_write+account_read
    &state=Yf3mE0k...
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256

(The line breaks are only there for reading.) All values are URL encoded.

Parameter Required Value
response_type yes code
client_id yes The ID the app is registered with
redirect_uri yes See Registered apps, at most 2000 characters
scope yes One or more names from Scopes, with spaces in between
state no Comes back unchanged with the answer. The app should always send it
code_challenge yes Exactly 43 characters, see step 1
code_challenge_method yes S256. The plain method is not supported

Rules:

  • Send every parameter once. A request which has a parameter in it twice is not reliable.
  • Do not send filesystem_dirs. The request is refused if it has that parameter. Which directories the app can use is for the user to choose.
  • Other parameters are ignored.

What the user sees:

  1. If they are not logged in to Nova in this browser, the login page. After logging in they continue to the next step by themselves.
  2. A page which says that the app (by the name it is registered with) wants access to their account, on which account they are logged in, and what the app will be able to do. If the app asked for a filesystem scope they can pick directories to limit the app to.
  3. The buttons Approve and Deny.

4. Receive the answer#

When the user chooses, the browser makes a GET request to the redirect URI.

If they approved:

GET /oauth/callback?code=75e48c59-0b1d-4e9a-9d0c-3c1f6d2b8a11&state=Yf3mE0k...

If they denied:

GET /oauth/callback?error=access_denied&state=Yf3mE0k...

The app must check that state is the value it sent, and ignore the request if it is not. It answers the browser with a short page which says that the user can close the tab and go back to the app, and then stops listening.

The app does not always get an answer. When the request is not valid the user stays on an error page of Nova and the browser is not sent back, see Errors on the authorization page. The user can also just close the tab. So the app needs a way to cancel a login which is waiting, and should give up by itself after some minutes.

5. Trade the code for the key#

The code is valid for five minutes and can be used once. The app sends it to the token endpoint right away:

POST https://dev.nova.storage/api/user/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=75e48c59-0b1d-4e9a-9d0c-3c1f6d2b8a11
&redirect_uri=http%3A%2F%2F127.0.0.1%3A41234%2Foauth%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Parameter Required Value
grant_type yes authorization_code
code yes The code from step 4
redirect_uri yes The same string as in step 3, with the same port
code_verifier yes The verifier from step 1

Do not send an Authorization header with this request. (A library which sends the client ID as the user name of a Basic header with an empty password does work. A password in that header is taken for an API key.) client_id is allowed in the form but not needed.

The answer to a good request has status 200 and this JSON body:

{
	"access_token": "c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22",
	"token_type": "Bearer",
	"scope": "filesystem_read filesystem_write account_read",
	"filesystem_dirs": []
}
  • access_token is the API key. Keep it secret and store it where the operating system keeps credentials, if there is such a place.
  • scope is what the app asked for.
  • filesystem_dirs is the list of directories the user limited the app to. An empty list means there is no limit. Store this list together with the key, see Directory limits. A key without the session_read scope has no way to ask for it later.
  • There is no expires_in and no refresh_token.

A request which is refused has status 400 and a body in the format of RFC 6749 section 5.2:

{
	"error": "invalid_grant",
	"error_description": "The code is not valid, it expired, it was used before, or the redirect_uri or code_verifier does not match the request it was given out for"
}
error Cause
invalid_request A parameter is missing or malformed, or grant_type is not authorization_code
invalid_grant The code is unknown, expired or used, or redirect_uri or code_verifier do not match

After either error the login has to start again from step 1. Do not retry the same code.

6. Use the key#

Send the key with every API request in this header, with exactly this spelling, a capital B and one space:

Authorization: Bearer c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22

HTTP Basic authentication with an empty user name and the key as the password works too.

Scopes#

The scope of a request is a list of these names with spaces in between. Ask for as little as the app needs: the user sees every permission on the page where they approve the app.

Scope What the key can do
filesystem_read List directories, read file information, download and search files
filesystem_write Upload, create directories, rename, move, delete, and change how files are shared
account_read GET /api/user (user name, e-mail address, plan, storage and transfer usage) and the usage statistics
session_read List the API keys of the account which can do no more than this key
session_write Create API keys which can do no more than this key
billing_read See invoices and transactions
billing_write Create invoices and change the subscription

A file manager needs filesystem_read filesystem_write account_read.

There is no scope for changing the account itself. The user name, e-mail address, password and two-factor login can only be changed by the user, logged in on the website. No API key which an app can get is able to do that.

A request can only be approved for permissions which the login session of the user has itself. For a normal login on the website that is all of them.

Directory limits#

On the authorization page the user can pick directories. The key then only works inside those directories, and the token response lists them in filesystem_dirs as directory IDs:

"filesystem_dirs": ["6m6r7854Ubzt491q4AJuCb", "kPH3q7JP4Syg6Fi5HSemA"]

How the app has to deal with that:

  • If the list is empty there is no limit. The home directory of the user is /api/filesystem/me, as usual.
  • If the list is not empty, do not use me. Every ID in the list is a root of its own. The path of something inside it is /api/filesystem/{id}/{path inside the directory}. Show the directories as the top level locations of the app.
  • The name of such a directory is in path[0].name of the response to GET /api/filesystem/{id}?stat. The path fields of the nodes in a response start with /{id}, where they would start with /me in the home directory.
  • Anything outside the listed directories is refused with status 400 and the error permission_denied. That goes for files the app may expect in the home directory too, like /me/.nova/bookmarks.json.
  • A rename can not move something from one listed directory to another: the old and the new path have to be under the same root.
  • The user can change the directories of the key afterwards, and its permissions, on the API keys page of the website. The app is not told. If requests which used to work are refused with permission_denied or key_permission_denied, the app should ask the user to log in again. That gives it a new key, with the directories as they are then. A key with the session_read scope can look itself up instead: it is the entry with "current": true in the response of GET /api/user/session, which has the fields filesystem_dirs and one boolean per scope.

Example with the first directory of the list above:

GET https://dev.nova.storage/api/filesystem/6m6r7854Ubzt491q4AJuCb?stat
Authorization: Bearer c7d8ca5d-3b0e-4b0a-9a5e-0f6f0c7a1b22
{
	"path": [
		{"id": "6m6r7854Ubzt491q4AJuCb", "type": "dir", "path": "/6m6r7854Ubzt491q4AJuCb", "name": "Backups"}
	],
	"base_index": 0,
	"children": [
		{"id": "MoDmdQKTq3P1FMPoRcoATw", "type": "file", "path": "/6m6r7854Ubzt491q4AJuCb/example.txt", "name": "example.txt"}
	],
	"permissions": {"owner": true, "read": true, "write": true, "delete": true}
}

(The nodes have more fields than are shown here.)

How long the key lives#

  • The key stays valid as long as it is used. It expires when it has not been used for 30 days.
  • The user can delete the key at any moment, on the API keys page of the website.
  • In both cases the next request gets status 401 with the error authentication_failed. There is no refresh token: the app forgets the key and starts the login again.
  • To sign out, the app deletes its own key with DELETE https://dev.nova.storage/api/user/session, with the key in the Authorization header. Every key can do this, whatever its scope. Do it whenever the user signs out of the app.

Errors#

Apart from the token endpoint, the API reports errors with an HTTP status and this JSON body. value is the stable name of the error.

{"success": false, "value": "authentication_failed", "message": "The provided API key is invalid, has been revoked or has expired"}
Status value Meaning
401 authentication_failed The key does not exist anymore. Log in again
401 authentication_required The request had no key
403 key_permission_denied The key does not have the scope which this endpoint needs
400 permission_denied The filesystem path is outside what the key or the user is allowed to use

Errors on the authorization page#

When the request of step 3 is not valid, the user gets a page which says that the app can’t be given access, with the message of the error. The browser is not sent back to the app. These are the errors, by the name they have in the API:

value Cause
oauth_client_invalid Unknown client_id, or a redirect_uri which the app did not register
oauth_scope_invalid A name in scope which is not in the table of scopes
oauth_dirs_invalid The request has a filesystem_dirs parameter
missing_field, enum_parse_failed, string_out_of_range A parameter is missing, has a value which is not allowed, or has the wrong length. The page names the parameter
key_permission_denied The login session of the user can not give out the permissions which were asked for

What is not supported#

  • Refresh tokens, client secrets, the implicit flow, the device flow and the plain PKCE method.
  • Redirect URIs with a custom scheme, like myapp://callback. Only the ones in the list of registered apps work. An app which can not listen on 127.0.0.1 while the browser is open, which happens on phones, needs another redirect URI registered first.
  • A discovery document. The URLs on this page are all there is.
  • Apps which run as a web page on another site: the API does not send the CORS headers a browser needs for that.

Checklist#

  1. A new code_verifier and state for every login, from a cryptographic random source.
  2. code_challenge is the SHA-256 hash of the verifier in base64url without = padding. Check it with the test values in step 1.
  3. The listener is on 127.0.0.1, and the redirect URI says 127.0.0.1.
  4. The path of the redirect URI is /oauth/callback.
  5. The login page opens in the default browser, not in a web view.
  6. The app checks state before it uses the code.
  7. The token request has the same redirect_uri as the authorization request, and no Authorization header.
  8. The app stores access_token and filesystem_dirs.
  9. If filesystem_dirs is not empty the app uses those IDs as roots, and never me.
  10. A waiting login can be cancelled, and gives up by itself.
  11. On status 401 authentication_failed the app asks the user to log in again.
  12. Signing out deletes the key with DELETE /api/user/session.

Reference implementation#

This is a complete login in Go with only the standard library. It was run against the API as it is described here.

// Package novaauth logs a user in to Nova with OAuth 2.0: the authorization
// code flow with PKCE and a loopback redirect. Standard library only.
package novaauth

import (
	"context"
	"crypto/rand"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"net"
	"net/http"
	"net/url"
	"strings"
)

// Token is the response of the token endpoint. Store all of it.
type Token struct {
	AccessToken    string   `json:"access_token"`
	TokenType      string   `json:"token_type"`
	Scope          string   `json:"scope"`
	FilesystemDirs []string `json:"filesystem_dirs"`
}

// random returns 43 characters which are safe in a URL
func random() string {
	b := make([]byte, 32)
	if _, err := rand.Read(b); err != nil {
		panic(err)
	}
	return base64.RawURLEncoding.EncodeToString(b)
}

// Login runs the whole flow and returns the API key of the user.
//
// base is the site, "https://dev.nova.storage". scope is a list of permissions
// with spaces in between. openBrowser has to open a URL in the default browser
// of the user. Cancel ctx to stop waiting for the user.
func Login(
	ctx context.Context,
	base, clientID, scope string,
	openBrowser func(url string) error,
) (*Token, error) {
	verifier, state := random(), random()
	sum := sha256.Sum256([]byte(verifier))
	challenge := base64.RawURLEncoding.EncodeToString(sum[:])

	// Any free port, on 127.0.0.1. "localhost" is not accepted
	listener, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		return nil, err
	}
	port := listener.Addr().(*net.TCPAddr).Port
	redirectURI := fmt.Sprintf("http://127.0.0.1:%d/oauth/callback", port)

	type result struct {
		code string
		err  error
	}
	results := make(chan result, 1)
	server := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		q := r.URL.Query()
		if r.URL.Path != "/oauth/callback" || q.Get("state") != state {
			// Not the answer to our request, keep waiting
			http.Error(w, "unexpected request", http.StatusBadRequest)
			return
		}

		var res result
		if q.Get("error") != "" {
			res.err = errors.New("login was not approved: " + q.Get("error"))
		} else if res.code = q.Get("code"); res.code == "" {
			res.err = errors.New("the callback has no code")
		}
		fmt.Fprintln(w, "You can close this tab and go back to the app.")

		select {
		case results <- res:
		default: // A second callback, the first one counts
		}
	})}
	go server.Serve(listener)
	defer server.Close()

	if err = openBrowser(base + "/oauth/authorize?" + url.Values{
		"response_type":         {"code"},
		"client_id":             {clientID},
		"redirect_uri":          {redirectURI},
		"scope":                 {scope},
		"state":                 {state},
		"code_challenge":        {challenge},
		"code_challenge_method": {"S256"},
	}.Encode()); err != nil {
		return nil, err
	}

	var res result
	select {
	case res = <-results:
	case <-ctx.Done():
		return nil, ctx.Err()
	}
	if res.err != nil {
		return nil, res.err
	}

	// Trade the code for the key. No Authorization header on this request
	req, err := http.NewRequestWithContext(
		ctx, "POST", base+"/api/user/oauth/token",
		strings.NewReader(url.Values{
			"grant_type":    {"authorization_code"},
			"code":          {res.code},
			"redirect_uri":  {redirectURI},
			"code_verifier": {verifier},
		}.Encode()),
	)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		var e struct {
			Error       string `json:"error"`
			Description string `json:"error_description"`
		}
		json.NewDecoder(resp.Body).Decode(&e)
		return nil, fmt.Errorf(
			"token request failed: %s: %s %s", resp.Status, e.Error, e.Description,
		)
	}

	var token Token
	if err = json.NewDecoder(resp.Body).Decode(&token); err != nil {
		return nil, err
	}
	return &token, nil
}

Using it. openBrowser is a function of the app which opens a URL in the default browser: xdg-open on Linux, rundll32 url.dll,FileProtocolHandler on Windows, open on macOS, or what the UI framework of the app has for it.

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()

token, err := novaauth.Login(
	ctx, "https://dev.nova.storage", "jevido-nova",
	"filesystem_read filesystem_write account_read", openBrowser,
)
if err != nil {
	return err
}

req, _ := http.NewRequest("GET", "https://dev.nova.storage/api/user", nil)
req.Header.Set("Authorization", "Bearer "+token.AccessToken)