JoseError unstable

The JoseError returned by the effect/jose modules, and the reasons it carries.

Every failure is one JoseError whose reason says what went wrong. Reasons for configuration, transport, and key-import problems carry a description and, when there is one, a cause. Reasons for failed authentication carry nothing: they never describe tokens, claims, plaintext, or key material.

Gotchas

Map the error before it reaches a client, for example SignatureVerificationFailed to a 401. Sending verification detail to clients is how oracles leak.

14 exports Since v4.1.1 Source

Errors

AlgorithmNotAllowed

unstable

Since v4.1.1

Reason for a token whose protected alg is not the key's algorithm or is outside the allowlist.

Signature

declare class AlgorithmNotAllowed extends YieldableError<this> & {
  readonly _tag: "AlgorithmNotAllowed";
} & Readonly<{}> {
  constructor(args: void);
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

AmbiguousKey

unstable

Since v4.1.1

Reason for a key set with more than one key matching the algorithm and key id.

Signature

declare class AmbiguousKey extends YieldableError<this> & {
  readonly _tag: "AmbiguousKey";
} & Readonly<{}> {
  constructor(args: void);
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

ClaimValidationFailed

unstable

Since v4.1.1

Reason for a registered claim or typ header that is missing, malformed, different from the expected value, or outside its validity window.

Signature

declare class ClaimValidationFailed extends YieldableError<this> & {
  readonly _tag: "ClaimValidationFailed";
} & Readonly<{
  readonly claim: "sub" | "iss" | "aud" | "exp" | "nbf" | "iat" | "jti" | "typ";
  readonly reason: "invalid" | "missing" | "mismatch" | "expired" | "notYetValid" | "tooOld" | "future";
}> {
  constructor(args: {
    readonly claim: "sub" | "iss" | "aud" | "exp" | "nbf" | "iat" | "jti" | "typ";
    readonly reason: "invalid" | "missing" | "mismatch" | "expired" | "notYetValid" | "tooOld" | "future";
  });
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

DecryptionFailed

unstable

Since v4.1.1

Reason for ciphertext that fails authenticated decryption.

Signature

declare class DecryptionFailed extends YieldableError<this> & {
  readonly _tag: "DecryptionFailed";
} & Readonly<{}> {
  constructor(args: void);
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

InvalidArgument

unstable

Since v4.1.1

Reason for an option or configuration value that the operation rejects before doing any work, such as a non-HTTPS key-set URL.

Signature

declare class InvalidArgument extends YieldableError<this> & {
  readonly _tag: "InvalidArgument";
} & Readonly<{
  readonly cause?: unknown;
  readonly description: string;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description: string;
  });
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

InvalidKey

unstable

Since v4.1.1

Reason for key material that cannot be imported, or that does not fit the selected algorithm or operation.

Signature

declare class InvalidKey extends YieldableError<this> & {
  readonly _tag: "InvalidKey";
} & Readonly<{
  readonly cause?: unknown;
  readonly description: string;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description: string;
  });
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

InvalidToken

unstable

Since v4.1.1

Reason for a malformed compact serialization, protected header, or payload, or for header parameters that are not supported, such as crit.

Signature

declare class InvalidToken extends YieldableError<this> & {
  readonly _tag: "InvalidToken";
} & Readonly<{
  readonly description: string;
}> {
  constructor(args: {
    readonly description: string;
  });
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

JoseError

unstable

Since v4.1.1

Error returned by the effect/jose modules.

See

isJoseError for narrowing unknown values

Signature

declare class JoseError extends YieldableError<this> & {
  readonly _tag: "JoseError";
} & Readonly<{
  readonly reason: JoseErrorReason;
}> {
  constructor(args: {
    readonly reason: JoseErrorReason;
  });
  readonly "~effect/jose/JoseError": "~effect/jose/JoseError";
  readonly cause: unknown;
  message: string;
}

Example Rejecting a token with a bad signature

import { Effect } from "effect"
import { JoseError } from "effect/jose"

const verify = Effect.fail(
  new JoseError.JoseError({ reason: new JoseError.SignatureVerificationFailed() })
)

const program = verify.pipe(
  Effect.catchReason("JoseError", "SignatureVerificationFailed", () => Effect.succeed("rejected"))
)

await Effect.runPromise(program) // => "rejected"

JoseErrorReason

type unstable

Since v4.1.1

Union of the reasons carried by JoseError.

Signature

type JoseErrorReason = InvalidToken | InvalidKey | InvalidArgument | AlgorithmNotAllowed | SignatureVerificationFailed | DecryptionFailed | KeyNotFound | AmbiguousKey | KeySetUnavailable | ClaimValidationFailed

KeyNotFound

unstable

Since v4.1.1

Reason for a key set with no key matching the algorithm and key id.

Signature

declare class KeyNotFound extends YieldableError<this> & {
  readonly _tag: "KeyNotFound";
} & Readonly<{}> {
  constructor(args: void);
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

KeySetUnavailable

unstable

Since v4.1.1

Reason for a remote key set that cannot be fetched or read, is cooling down after a failed refresh, or belongs to a closed layer.

Signature

declare class KeySetUnavailable extends YieldableError<this> & {
  readonly _tag: "KeySetUnavailable";
} & Readonly<{
  readonly cause?: unknown;
  readonly description: string;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly description: string;
  });
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

SignatureVerificationFailed

unstable

Since v4.1.1

Reason for a signature that does not authenticate the token.

Signature

declare class SignatureVerificationFailed extends YieldableError<this> & {
  readonly _tag: "SignatureVerificationFailed";
} & Readonly<{}> {
  constructor(args: void);
  readonly "~effect/jose/JoseError/Reason": "~effect/jose/JoseError/Reason";
  message: string;
}

Guards

isJoseError

unstable

Since v4.1.1

Checks whether a value is a JoseError.

Signature

declare function isJoseError(u: unknown): u is JoseError

isJoseErrorReason

unstable

Since v4.1.1

Checks whether a value is one of the reasons carried by JoseError.

Signature

declare function isJoseErrorReason(u: unknown): u is JoseErrorReason