Developers · Sign-in

Sign in with SpiffyVault

People sign in to your site with the SpiffyVault app on their phone. The app signs your challenge with a key it made for your site alone, and you get a public key that is the same every time they come back. There are no passwords, no email addresses and no third party.

The protocol is OIAP-v2. It needs SpiffyVault 1.0.0, build 22 or later; earlier builds read only OIAP-v1, which no longer works. Your server makes a challenge and checks one Ed25519 signature. The @spiffyvault/sign-in package does both for you, and shows the challenge in your page.

How it works

On a computer:

  1. Your server makes a challenge and a 6-digit code.
  2. Your page shows the challenge as a QR code, with the code beside it.
  3. The user scans the QR code with SpiffyVault, which shows your name and domain, and types the code into the app.
  4. The app signs the challenge and the code with the user's key for your site, and sends the answer to your callback URL.
  5. Your server checks the signature, and the browser that asked is signed in.

On a phone, the page shows a button instead. A tap opens SpiffyVault; after the user approves, the app opens your one-time return link in the phone's browser, and that browser is signed in. There is no code to type.

With the package

Install @spiffyvault/sign-in with npm install @spiffyvault/sign-in; its source is in spiffyvault-js. On your server:

import { SignInSite } from '@spiffyvault/sign-in';

const site = new SignInSite({
  domain: 'shop.example',
  callback: 'https://shop.example/sign-in/callback',
  name: 'Example Shop',
  returnBase: 'https://shop.example/sign-in/return',
});
Your endpointCalls
POST /sign-in/startsite.start({ mode, browser, place }). browser is your id for this browser, from a cookie you set here.
GET /sign-in/pollsite.poll(nonce, browser). On signed-in, start a session for publicKey.
POST /sign-in/callbacksite.answer(body). Send its status and body.
GET /sign-in/returnsite.redeem(t). Start a session for the key, then redirect.

SignInSite keeps sign-ins in memory, for one server process. With more than one, send every request for one sign-in to the same process (route by the nonce or t parameter, or use sticky sessions). A shared store alone is not enough: two processes can both read a sign-in before either writes it back, and then one attempt per challenge, and one use per return token, no longer hold. The same goes for a server in another language: take a challenge or token from your store in one atomic step.

In your page:

import { mountSignIn } from '@spiffyvault/sign-in/browser';

mountSignIn(document.getElementById('sign-in'), {
  start: async (mode) => (await fetch('/sign-in/start', { method: 'POST', body: mode })).json(),
  poll: async (nonce) => (await fetch(`/sign-in/poll?nonce=${nonce}`)).json(),
  onSignedIn: () => location.reload(),
});

The package has a complete example site. The rest of this page is the protocol, for a server in another language.

1. Make a challenge

The challenge is a JSON object:

{
  "v": 2,
  "domain": "shop.example",
  "nonce": "AAECAwQFBgcICQoLDA0ODw",
  "ts": 1793000000,
  "mode": "code",
  "callback": "https://shop.example/sign-in/callback",
  "name": "Example Shop",
  "place": "Lagos, Nigeria"
}
FieldValue
v2
domainYour domain, in lowercase, with no port. The user sees it, and their key for your site is made from it, so keep it the same. Your callback and return links must be on exactly this host.
nonce16 random bytes or more, as base64url (22 to 128 characters). A new one for each challenge.
tsThe time now, in seconds since 1970 (UTC).
modecode when your page is on a computer; return when it is on a phone.
callbackWhere the app sends the answer: HTTPS, on exactly the host domain names. A subdomain is refused.
nameYour site's name, 1 to 64 characters, shown to the user.
placeOptional. Where the browser that asked appears to be, for example from its IP address: 1 to 64 characters. The app shows it.

No field may contain a line break. In mode code, also make a 6-digit code with a secure random generator. Keep the challenge and the code on your server, keyed by the nonce, with the id of the browser that asked. Never put the code in the challenge.

2. Show it

Encode the JSON as base64url, without padding, and put it in a spiffyvault://auth link:

spiffyvault://auth?c=<base64url>

3. Check the answer

When the user approves, the app sends a POST to your callback with Content-Type: application/json:

{
  "v": 2,
  "nonce": "AAECAwQFBgcICQoLDA0ODw",
  "public_key": "…64 hex characters…",
  "signature": "…128 hex characters…"
}

public_key is the user's key for your site, an Ed25519 key as lowercase hex. It is the user's id on your site. The signed message is these nine lines joined with a line feed, with no line feed at the end, in UTF-8, made from your stored challenge:

OIAP-v2
<domain>
<nonce>
<ts>
<mode>
<callback>
<name>
<place, or nothing>
<the code you showed, or nothing in mode return>

On your server:

  1. Find the challenge by nonce. Refuse an unknown nonce, or one already answered.
  2. Mark it answered now, whatever happens next. Each challenge has one try, so a wrong code cannot be tried again.
  3. Refuse it if it is more than five minutes old.
  4. Check the signature. Node.js needs no extra package:
import { createPublicKey, verify } from 'node:crypto';

// Checks an OIAP-v2 answer against the challenge and code you stored.
export function verifyAnswer(c, code, body) {
  const message = ['OIAP-v2', c.domain, c.nonce, String(c.ts), c.mode, c.callback, c.name,
    c.place ?? '', c.mode === 'code' ? code : ''].join('\n');
  const publicKey = createPublicKey({
    key: { kty: 'OKP', crv: 'Ed25519', x: Buffer.from(body.public_key, 'hex').toString('base64url') },
    format: 'jwk',
  });
  return verify(null, Buffer.from(message, 'utf8'), publicKey, Buffer.from(body.signature, 'hex'));
}

Then answer:

CaseStatusBody
Signed in, mode code200{"ok": true}
Signed in, mode return200{"ok": true, "return_url": "https://shop.example/sign-in/return?t=…"}, a one-time link on your domain
Refused4xx{"ok": false, "error": "…"} with code (wrong code or bad signature), expired, used or unknown

The app tells the user which it was. It opens a return link only when it is HTTPS on your domain.

4. Finish in the browser

The answer goes from the phone to your server, not to the browser.

What the app checks

SpiffyVault refuses a challenge, and does not ask the user, when:

For development, when domain is localhost, 127.0.0.1 or a private IPv4 address, the callback may be plain HTTP, on exactly that host.

Phishing

The typed code proves that the user can see the browser that asked. It stops a QR code that reaches someone without its page: a forwarded picture, a printed code, a code in a message. It does not stop a fake page that copies your challenge and your code in real time. Against that, the app tells the user to type only a code shown on your domain, and shows the place you send: in that attack it is where the attacker is. Sign-in on the phone, with a return link, cannot be passed on in this way.

The nonce is in the QR code, so anyone who sees the code can post a wrong answer to your callback and use up that challenge: one attempt per challenge. That gets them nothing; the user starts the sign-in again.

Privacy

Test it

The package's example site runs on your computer, at http://localhost:8787/. The phone must reach its callback over HTTPS (Android refuses plain HTTP), so put it behind a tunnel, for example cloudflared tunnel --url http://localhost:8787, and start it with the address the tunnel prints: PUBLIC_URL=https://….trycloudflare.com npm run example. Open that address on a computer to scan, or on the phone to sign in there.