1auth

Collection of modules to assist in user authentication and session management.

1Auth is like an ORM for `accounts`, `authentications`, `messengers`, `sessions` with extensibility to ensure they have a consistent API and ensure that encoding/decoding/encryption/decryption are applied in a consistent way. All while enforcing industry defaults for cryptographic algorithms with an easy method to keep them up to date.

Default algorithms

• Symmetric encryption: chacha20-poly1305 (AES-256 GCM also supported)
• Symmetric signature: HMAC
• Asymmetric encryption: ECDSA
• Asymmetric encryption key: ECC P-384 (ECC P-512 also supported)
• Asymmetric signature: Ed25521 (future)
• Digest: SHA3-384 (SHA2-512, SHA3-512 also supported)
• Secret hash: Argon2id (timeCost:3, memoryCost: 2^15, slatLength: 16, outputLen: 64)
• Encoding: base64

FIPS 140-3 Level 4 can be achieved using aes-256-gcm.

Quick start

Install

npm i @1auth/store-dynamodb @1auth/notify-sqs @1auth/crypto @1auth/account-username @1auth/account @1auth/messenger @1auth/messenger-email-address @1auth/authn @1auth/authn-webauthn @1auth/authn-webauthn-passkey @1auth/authn-webauthn-securitykey @1auth/authn-recovery-codes @1auth/authn-access-token @1auth/session @1auth/session-dbsc

@1auth/authn-webauthn-passkey and @1auth/authn-webauthn-securitykey are optional presets over @1auth/authn-webauthn, each a separately configured instance, so PassKeys and security keys can be offered as separate factors.

@1auth/session-dbsc is optional. DBSC only ships in Chromium, so it hardens sessions where it is available and is a no-op everywhere else — @1auth/session stays the fallback.

Example

import * as store from '@1auth/store-dynamodb'
import * as notify from '@1auth/notify-sqs'
import crypto from '@1auth/crypto'

import account from '@1auth/account'
import accountUsername, {
  exists as usernameExists
} from '@1auth/account-username'

import messenger from '@1auth/messenger'
import messengerEmailAddress from '@1auth/messenger-email-address'

import authn from '@1auth/authn'
import webauthn from '@1auth/authn-webauthn'
import recoveryCodes from '@1auth/authn-recovery-codes'
import recoveryCode from './authn/authn-recovery-code/index.js'
import accessToken from '@1auth/authn-access-token'

import sessionDBSC from '@1auth/session-dbsc'

// 12h chosen based on OWASP ASVS
const sessionExpire = 12 * 60 * 60
// 10d chosen based on EFF DNT Policy
const ttlExpire = 10 * 24 * 60 * 60

store.default({
  timeToLiveExpireOffset: ttlExpire - sessionExpire
})
notify.default({
  queueName: process.env.QUEUE_NAME ?? 'notify-queue'
})

// Passed in via ENV for example only
crypto({
  symmetricEncryptionKey: process.env.SYMMETRIC_ENCRYPTION_KEY ?? '',
  symmetricSignatureSecret: process.env.SYMMETRIC_SIGNATURE_SECRET ?? '',
  digestChecksumSalt: process.env.DIGEST_CHECKSUM_SALT ?? '',
  digestChecksumPepper: process.env.DIGEST_CHECKSUM_PEPPER ?? ''
})

account({
  store,
  notify,
  encryptedFields: ['value','name', 'locale']
})
accountUsername({
  usernameBlacklist: ['root', 'admin', 'sa']
})

messenger({
  store,
  notify,
  encryptedFields: ['value']
})
messengerEmailAddress()

authn({
  store,
  notify,
  usernameExists: [usernameExists],
  encryptedFields: ['value', 'name']
})
webauthn({
  origin: process.env.ORIGIN,
  name: 'Organization Name',
  userVerification: 'preferred'
})
recoveryCodes()
accessToken()

sessionDBSC({
  store,
  notify,
  expire: sessionExpire
})

Architecture

License

Licensed under MIT License. Copyright (c) 2020-2026 will Farrell and contributors.