skapi-js 2.4.0: free two-step login, no more SMS, and a lighter SDK

Hello! skapi-js 2.4.0 is here. Your users can now protect their accounts with two-step login, free for every project. The SDK is lighter than ever, and a long list of fixes makes sign-in and sessions sturdier. Here's what's inside:

  • Two-step login with an authenticator app (MFA), free for every project.
  • Phone number verification is retired, because a paid text message per user does not scale.
  • Fewer dependencies and a lighter SDK: skapi-js now uses its own sign-in code, and its npm package is 59% smaller.
  • A few breaking changes, most of them in record encryption, and the fixes we most want you to have.

For most apps, upgrading needs no code changes. The last section of this article says when it does, and every change is in the Version History.

Two-step login with an authenticator app

Users can now protect their account with an authenticator app: any app that shows a 6 digit code that changes every 30 seconds. With it turned on, logging in takes the password and then the code from the app on their phone. Someone who learns the password still cannot log in without the phone.

It is optional and each user decides for their own account. It also costs nothing: not you, not your users, and nothing per login. Codes are never sent by SMS.

Turning it on

// 1. Show the QR code
const { uri, secret } = await skapi.setupMFA();
// draw `uri` as a QR code; show `secret` for users who type it in

// 2. Confirm a code from the app
await skapi.enableMFA({ code: '123456' }); // 'SUCCESS: MFA has been enabled.'

The app lists the account under your project's name and the user's e-mail.

Logging in with a code

try {
    await skapi.login({ email, password });
}
catch (err) {
    if (err.code === 'MFA_REQUIRED') {
        // ask for the code from the app, then:
        await skapi.verifyMFA({ code });
    }
}

login() checks the password first, then rejects with MFA_REQUIRED to ask for the code. verifyMFA() finishes the login and returns the user's profile, just as login() does. A wrong code can be retried with the next one. getMFAStatus() tells a settings page whether it is on, and disableMFA() turns it off.

If a user loses their phone, an admin of your project turns it off for them with disableUserMFA(), and they log in with their password again. See Two-Step Login (MFA) for the full guide, with an HTML form example.

Phone number verification is retired

verifyPhoneNumber() sent a text message with a code. Every one of those messages had a price, set by the country it went to. Sending them everywhere also means registering as a sender with carriers, country by country. So the cost grows with every user who signs up, and the setup grows with every country they sign up from. Skapi does not support verification methods that do not scale and can be costly for the people building on it.

An authenticator app protects an account better. It is free, it works the same in every country, and it does not depend on a phone network delivering a message. So 2.3.0 removed phone verification and put two-step login in its place. Skapi now sends no text messages at all.

What this means for your app:

  • If you never called verifyPhoneNumber(), nothing changes.
  • phone_number stays a profile field. Users can still save their number with updateProfile().
  • phone_number_public no longer needs a verified number, the same as address_public.
  • phone_number_verified is no longer set. An account verified earlier keeps true until its number changes.
  • The Phone verification SMS box is gone from the dashboard's Automated Emails page. E-mail verification and its template are unchanged.

If your app calls verifyPhoneNumber(), replace it with the two-step login calls above:

// Before
await skapi.verifyPhoneNumber();          // sent a text message
await skapi.verifyPhoneNumber({ code });  // verified the number

// After
const { uri } = await skapi.setupMFA();   // show uri as a QR code
await skapi.enableMFA({ code });          // a code from the app

The details are on the Deprecated page.

Fewer dependencies, a lighter SDK

Until 2.3.0, skapi-js signed users in through amazon-cognito-identity-js. That general-purpose library brought five more packages with it, and Skapi used only a small part of it. skapi-js now does that part with its own sign-in code, written for Skapi and nothing else. In 2.4.0 the package lost its remaining weight: a one-line license header instead of the whole license text in every file, no duplicate type file, and source maps that no longer embed the sources.

skapi-js 2.2.35 2.4.0
npm package, unpacked 8.6 MB 3.5 MB (59% smaller)
Browser build (skapi.js) 355 KB 288 KB (19% smaller)
Browser build, gzipped 106 KB 87 KB
Packages npm install skapi-js adds 8 2

Nothing changes in how you call any method. Errors, error codes and messages are the same. Sign-in still never sends the password itself: it uses the same SRP exchange as before. The sign-in math is faster too, because the new code does its large-number calculations with the number type built into every modern browser and Node.js. On our test machine, one sign-in took 58 ms instead of 414 ms.

Your users stay signed in. The SDK saves a session under the same names it always has. A session from an older skapi-js opens in the new one, and the other way round, so an upgrade signs nobody out.

Before release, we checked the new sign-in code against the old library step by step:

  • The password proof matched byte for byte in 2,000 of 2,000 runs.
  • The same 20 account steps gave identical results on both versions, from sign-up to a password reset.
  • Sessions opened after upgrading and after downgrading.
  • A connection cut during a token refresh did not sign the user out.
  • 300 sign-ins in a row succeeded on a development region, with a password in Korean and an emoji.

2.4.0: what to check before you upgrade

2.4.0 removes and renames a few methods. Most of them are in record encryption, so most apps are not affected.

  • secureRequest() is removed. To call your own API, use forwardRequest(). Store a key on the Secret Keys page, put $CLIENT_SECRET in a header your API checks, and add skapiHeaders: true so your API knows who is calling.

  • Encryption recovery is redesigned. The two recovery methods are renamed:

    • regenerateRecoveryCode() is now regenerateEncryptionRecoveryCode().
    • unlockWithRecoveryCode() is now unlockEncryptionWithRecoveryCode().

    takeRecoveryCode() is gone: the recovery code is shown once, in getConnectionInfo() as encryption_recovery.code.

  • unlockEncryption() no longer sets up encryption. It only opens encryption that was set up at the user's first login with their password. This way, data can never be sealed under a mistyped password.

  • The minPasswordLength encryption option and reference_private_key in postRecord() are removed. The SDK sends the key for a referenced private record on its own.

The details, with before-and-after code, are in Encrypting Private Data and the Version History.

The fixes we most want you to have

This release fixes more than we could list here. These are the fixes most likely to have touched your app:

  • Sessions hold up better.
    • Only one token refresh runs at a time.
    • A logout always wins over a refresh that is still running.
    • A session left idle past its expiry no longer fails on changePassword(), updateProfile() or verifyEmail().
    • An expired session survives a page load with no network, instead of being signed out.
  • Sign-in always answers. login(), openIdLogin() and anonymousLogin() could stay pending forever when the session could not be read back. Now they reject with an error you can catch.
  • Sign-in works on every Node.js version. On Node 18, 20.0 to 20.15 and 22.0 to 22.2, import { Skapi } from 'skapi-js' ended signed out even with the right password. Now the session is kept in memory for as long as the process runs.
  • forwardRequest() with poll and onResponse works again. It had been broken since 1.6.0.
  • Deleting files by URL works for any file name, including names with spaces or non-English characters, which used to delete nothing.
  • Access is checked on every request.
    • Private access keys expire after 1 hour and renew on their own, so a user who loses access to a private record loses it within the hour.
    • Signed file links check access each time they are opened.
  • A forgotten-password reset signs the account out on every other device.

Upgrading

npm install skapi-js@latest

or, on a page:

<script src="https://cdn.jsdelivr.net/npm/skapi-js@2.4.0/dist/skapi.js"></script>

No code changes are needed unless your app calls verifyPhoneNumber() or secureRequest(), or uses record encryption's recovery methods. Your users stay signed in. To check, run await skapi.version() in the browser console on your page. It should say 2.4.0 or later.

Building for another platform? Skapi is now on iOS, macOS, Android, Python and Java.

Thank you for building with Skapi, and for every question and bug report you send our way. Most of the fixes in this release started as one of them.

← Back to all articles