PgAuth

Password authentication for the PostgreSQL protocol: MD5 and SCRAM-SHA-256.

Message framing lives in PgProtocol - SASL payloads travel as opaque bytes - so this module only computes what goes inside them. Cleartext authentication needs nothing from here; send the password as a PasswordMessage.

SCRAM-SHA-256-PLUS is not implemented: channel binding needs the TLS socket, which this codec does not own. Passwords are used as UTF-8 without SASLprep normalisation, so non-ASCII passwords that require normalisation are not supported. Server iteration counts above 1,000,000 are rejected before password derivation.

9 exports Added in v4.0.0 Source

Authentication

md5Password

Added in v4.0.0 Source

Computes the legacy PostgreSQL MD5 password response.

Signature

declare function md5Password(options: {
  readonly password: string;
  readonly salt: Uint8Array;
  readonly user: string;
}): Result<string, AuthError>

Errors

AuthError

Added in v4.0.0 Source

Failure returned when an authentication exchange cannot be completed.

Signature

declare class AuthError extends YieldableError<this> & {
  readonly _tag: "PgAuthError";
} & Readonly<{
  readonly message: string;
}> {
  constructor(args: {
    readonly message: string;
  });
}

SCRAM

SCRAM_SHA_256

Added in v4.0.0 Source

The only SASL mechanism this module implements.

Signature

declare const SCRAM_SHA_256: "SCRAM-SHA-256"

scramContinue

Added in v4.0.0 Source

Processes the server's SCRAM challenge and creates the client proof.

Signature

declare function scramContinue(state: ScramFirst, challenge: Uint8Array): Result<{
  readonly response: Uint8Array;
  readonly state: ScramFinal;
}, AuthError>

ScramFinal interface

Added in v4.0.0 Source

State after the client's final message, awaiting the server signature.

Signature

interface ScramFinal {
  readonly _tag: "ScramFinal";
  readonly serverSignature: Uint8Array;
}

scramFinish

Added in v4.0.0 Source

Verifies the server's final SCRAM message.

Signature

declare function scramFinish(state: ScramFinal, challenge: Uint8Array): Result<void, AuthError>

ScramFirst interface

Added in v4.0.0 Source

State after the client's first message, awaiting the server's challenge.

Signature

interface ScramFirst {
  readonly _tag: "ScramFirst";
  readonly clientFirstMessageBare: string;
  readonly clientNonce: string;
  readonly password: string;
}

scramInit

Added in v4.0.0 Source

Creates the first SCRAM-SHA-256 client message.

Signature

declare function scramInit(options: {
  readonly nonce: string;
  readonly password: string;
}): Result<{
  readonly response: Uint8Array;
  readonly state: ScramFirst;
}, AuthError>

ScramState type

Added in v4.0.0 Source

The SCRAM exchange state.

Signature

type ScramState = ScramFirst | ScramFinal