2fauth.js

A JavaScript module for interacting with a 2FAuth instance.

Usage

1. Initialize your project using npm and/or tsc.

mkdir new-project
cd new-project

npm init -y
tsc --init

2. Install the module.

# with npm
npm add @povario/2fauth.js

# OR with pnpm
pnpm add @povario/2fauth.js

3. Get your API URL and token and have fun:

import { TwoAuthApi } from "@povario/2fauth.js";

async function main() {
  const api = new TwoAuthApi("http://your-api-url-here", "your-token-here");
  const res = await api.accounts.getAll();

  console.log(res);
}

main();

Additional info

I won't go into the full documentation of the 2FAuth API, as that can be viewed here. However, the following documented API routes correspond to the following method calls:

Groups

• GET /api/v1/groups:

await api.groups.getAll();

• POST /api/v1/groups:

await api.groups.create("groupName");

• GET /api/v1/groups/{id}:

// with "1" being a group ID

await api.groups.get(1);

• PUT /api/v1/groups/{id}:

// with "1" being a group ID

await api.groups.update(1, "newGroupName");

• DELETE /api/v1/groups/{id}:

// with "1" being a group ID

await api.groups.delete(1);

• POST /api/v1/groups/{id}/assign:

// with "1" being a group ID and "1, 2, 3" being IDs of accounts

await api.groups.assign(1, [1, 2, 3]);

• GET /api/v1/groups/{id}/twofaccounts:

// with "1" being a group ID and setting the method to return accounts with their secrets as well

await api.groups.getAccounts<true>(1, true);

Icons

• POST /api/v1/icons:

// with "image" being a FormData containing a single image

await api.icons.upload(image);

• POST /api/v1/icons/default:

await api.icons.query({
  service: "1password",
  iconCollection: "selfh"
});

• DELETE /api/v1/icons/{filename}:

await api.icons.delete("filename.png");

OTP

• GET /api/v1/twofaccounts/{id}/otp:

// with "1" being an account ID

await api.otp.get(1);

• POST /api/v1/twofaccounts/otp:

// with an object containing a TOTP account

await api.otp.create({
  service: "MySite",
  account: "john.doe",
  icon: "ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png",
  otp_type: "totp",
  secret: "GJTGC5LUNA",
  digits: 6,
  algorithm: "sha1",
  period: 30,
  counter: 15,
  group_id: 1
});

QRCode

• GET /api/v1/twofaccounts/{id}/qrcode:

// with "1" being an account ID

await api.qrcode.get(1);

• POST /api/v1/qrcode/decode:

// with "qrCode" being a FormData containing a QR Code image

await api.qrcode.decode(qrCode);

Settings

• GET /api/v1/settings:

await api.settings.getAll();

• POST /api/v1/settings:

// with an object containing an example setting

await api.settings.add({
  key: "useEncryption",
  value: true
});

• GET /api/v1/settings/{name}:

await api.settings.get("settingName");

• PUT /api/v1/settings/{name}:

await api.settings.update("settingName", "newSettingValue");

• DELETE /api/v1/settings/{name}:

await api.settings.delete("settingName");

TwoFAccounts

• GET /api/v1/twofaccounts:

// setting the method to return the accounts with their secrets

await api.accounts.getAll<true>();

• POST /api/v1/twofaccounts:

// with a TOTP account object

await api.accounts.create({
  service: "MySite",
  account: "john.doe",
  icon: "ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png",
  otp_type: "totp",
  digits: 6,
  algorithm: "sha1",
  secret: "GJTGC5LUNA",
  period: 30,
  counter: null
});

• DELETE /api/v1/twofaccounts:

// with "1, 2, 3" being account IDs

await api.accounts.deleteMany([1, 2, 3]);

• GET /api/v1/twofaccounts/{id}:

// with "1" being an account ID, and returning the secret with it

await api.accounts.get<true>(1, true);

• PUT /api/v1/twofaccounts/{id}:

// with "1" being an account ID, and updating the account username

await api.accounts.update(1, {
  account: "john.doe",
});

• DELETE /api/v1/twofaccounts/{id}:

// with "1" being an account ID

await api.accounts.delete(1);

• POST /api/v1/twofaccounts/migration:

// with a Google Authenticator payload, and returning the secret

await api.accounts.migrate<true>(
  "otpauth-migration://offline?data=w0SnrWITY/RFhILYWNjb3VudF9iaXMaC3NlcnZpY2VfYmlzIAEoATACEAEYASAA",
  true,
);

• POST /api/v1/twofaccounts/preview:

// with an example OTPAuth URI

await api.accounts.preview("otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite&period=30&algorithm=sha1&digits=6&image=https://www.example.com/image.png");

• POST /api/v1/twofaccounts/reorder:

// with "1, 2, 3" being account IDs

await api.accounts.reorder([1, 2, 3]);

• PATCH /api/v1/twofaccounts/withdraw:

// with "1, 2, 3" being account IDs

await api.accounts.withdraw([1, 2, 3]);

• GET /api/v1/twofaccounts/export:

// with "1, 2, 3" being account IDs, and the export type set to "otpauth"

await api.accounts.export<"otpauth">([1, 2, 3], true);

• GET /api/v1/groups/{id}/twofaccounts:

// with "1" being a group ID, and setting the method to return secrets

await api.accounts.getAllInGroup<true>(1, true);

User

• GET /api/v1/user:

await api.self.getSelf();

User Preference

• GET /api/v1/user/preferences:

await api.prefs.getAll();

• GET /api/v1/user/preferences/{name}:

await api.prefs.get("settingName");

• PUT /api/v1/user/preferences/{name}:

// explicitly setting the type

await api.prefs.update<string, Setting<string>>("settingName", "newSettingValue");

Users

• GET /api/v1/users:

await api.users.getAll();

• POST /api/v1/users:

await api.users.create({
  name: "Name",
  email: "[email protected]",
  password: "password",
  password_confirmation: "password",
  is_admin: false
});

• GET /api/v1/users/{id}:

// with "1" as a user ID

await api.users.get(1);

• DELETE /api/v1/users/{id}:

// with "1" as a user ID

await api.users.delete(1);

• PATCH /api/v1/users/{id}/promote:

// with "1" as a user ID

await api.users.editAdmin(1, true)

• PATCH /api/v1/users/{id}/password/reset:

// with "1" as a user ID

await api.users.resetPassword(1);

• DELETE /api/v1/users/{id}/pats:

// with "1" as a user ID

await api.users.revokeATs(1);

• GET /api/v1/users/{id}/authentications:

// with "1" as a user ID, "5" as the maximum amount of records to return, and "2" as the period of time in months to search

await api.users.getLoginHistory(1, 5, 2);

• DELETE /api/v1/users/{id}/credentials:

// with "1" as a user ID

await api.users.revokeWebAuthn(1);