Skip to main content

Interface: IAuthenticationService

Defined in: src/types/interfaces/auth.interface.ts:339

Authentication service interface.

Remarks​

Provides DID-based authentication for AT Protocol users. Issues short-lived JWTs for session management.

Example​

const authService = container.resolve<IAuthenticationService>('IAuthenticationService');

const result = await authService.authenticateWithDID(
  'did:plc:abc123' as DID,
  { type: 'app_password', value: 'my-app-password' }
);

if (result.success) {
  console.log('Access token:', result.sessionToken?.accessToken);
} else if (result.mfaRequired) {
  console.log('MFA required:', result.mfaChallenge?.methods);
}

Methods​

authenticateWithDID()​

authenticateWithDID(did, credential): Promise<AuthenticationResult>

Defined in: src/types/interfaces/auth.interface.ts:358

Authenticate user via DID and PDS credential verification.

Parameters​

did​

DID

User's decentralized identifier

credential​

AuthCredential

Authentication credential

Returns​

Promise<AuthenticationResult>

Authentication result with session token or MFA challenge

Remarks​

Verifies the credential with the user's PDS and issues a Chive session token upon successful authentication.

Rate limit: 5 attempts per 15 minutes per IP address.

Throws​

AuthenticationError if credential verification fails

Throws​

RateLimitError if rate limit exceeded

completeMFAChallenge()​

completeMFAChallenge(challengeId, method, value): Promise<AuthenticationResult>

Defined in: src/types/interfaces/auth.interface.ts:440

Complete MFA challenge.

Parameters​

challengeId​

string

Challenge ID from MFAChallenge

method​

MFA method type used

"webauthn" | "totp" | "backup_code"

value​

string

MFA code or credential

Returns​

Promise<AuthenticationResult>

Authentication result with session token

Remarks​

Verifies the MFA code/credential and completes authentication if successful.

Throws​

AuthenticationError if MFA verification fails

issueSessionToken()​

issueSessionToken(did, options?): Promise<SessionToken>

Defined in: src/types/interfaces/auth.interface.ts:374

Issue JWT session token for authenticated user.

Parameters​

did​

DID

Authenticated user's DID

options?​

TokenOptions

Token options

Returns​

Promise<SessionToken>

Session token with access and optional refresh token

Remarks​

Generates a new JWT access token and optional refresh token. The access token is signed with ES256 and includes the user's DID and granted scopes.

refreshToken()​

refreshToken(refreshToken): Promise<SessionToken>

Defined in: src/types/interfaces/auth.interface.ts:390

Refresh access token using valid refresh token.

Parameters​

refreshToken​

string

Single-use refresh token

Returns​

Promise<SessionToken>

New session token with rotated refresh token

Remarks​

Validates the refresh token and issues a new access token. The refresh token is rotated (single-use) for security.

Throws​

AuthenticationError if refresh token is invalid or reused

revokeToken()​

revokeToken(token): Promise<void>

Defined in: src/types/interfaces/auth.interface.ts:405

Revoke token and invalidate session.

Parameters​

token​

string

Access or refresh token to revoke

Returns​

Promise<void>

Remarks​

Adds the token to a blacklist in Redis. The token will be rejected for all subsequent requests until it naturally expires.

This method is idempotent.

verifyToken()​

verifyToken(token): Promise<TokenClaims>

Defined in: src/types/interfaces/auth.interface.ts:422

Verify JWT and extract claims.

Parameters​

token​

string

JWT access token

Returns​

Promise<TokenClaims>

Token claims if valid

Remarks​

Validates the JWT signature, expiration, issuer, and audience. Checks if the token has been revoked.

Throws​

TokenExpiredError if token has expired

Throws​

TokenValidationError if signature is invalid or token is revoked