effect 4.1.0 → 4.1.2

package/src/jose/JoseError.ts

@@ -0,0 +1,329 @@
+/**
+ * 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.
+ *
+ * @stability unstable
+ * @since 4.1.1
+ */
+import * as Data from "../Data.ts"
+import * as Predicate from "../Predicate.ts"
+
+const TypeId = "~effect/jose/JoseError" as const
+const ReasonTypeId = "~effect/jose/JoseError/Reason" as const
+
+/**
+ * Reason for a malformed compact serialization, protected header, or payload,
+ * or for header parameters that are not supported, such as `crit`.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class InvalidToken extends Data.TaggedError("InvalidToken")<{
+  readonly description: string
+}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return this.description
+  }
+}
+
+/**
+ * Reason for key material that cannot be imported, or that does not fit the
+ * selected algorithm or operation.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class InvalidKey extends Data.TaggedError("InvalidKey")<{
+  readonly description: string
+  readonly cause?: unknown
+}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return this.description
+  }
+}
+
+/**
+ * Reason for an option or configuration value that the operation rejects
+ * before doing any work, such as a non-HTTPS key-set URL.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class InvalidArgument extends Data.TaggedError("InvalidArgument")<{
+  readonly description: string
+  readonly cause?: unknown
+}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return this.description
+  }
+}
+
+/**
+ * Reason for a token whose protected `alg` is not the key's algorithm or is
+ * outside the allowlist.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class AlgorithmNotAllowed extends Data.TaggedError("AlgorithmNotAllowed")<{}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return "The token algorithm is not allowed"
+  }
+}
+
+/**
+ * Reason for a signature that does not authenticate the token.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class SignatureVerificationFailed extends Data.TaggedError("SignatureVerificationFailed")<{}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return "Could not verify the signature"
+  }
+}
+
+/**
+ * Reason for ciphertext that fails authenticated decryption.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class DecryptionFailed extends Data.TaggedError("DecryptionFailed")<{}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return "Could not decrypt the token"
+  }
+}
+
+/**
+ * Reason for a key set with no key matching the algorithm and key id.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class KeyNotFound extends Data.TaggedError("KeyNotFound")<{}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return "No key matches the algorithm and key id"
+  }
+}
+
+/**
+ * Reason for a key set with more than one key matching the algorithm and key
+ * id.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class AmbiguousKey extends Data.TaggedError("AmbiguousKey")<{}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return "More than one key matches the algorithm and key id"
+  }
+}
+
+/**
+ * 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.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class KeySetUnavailable extends Data.TaggedError("KeySetUnavailable")<{
+  readonly description: string
+  readonly cause?: unknown
+}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return this.description
+  }
+}
+
+/**
+ * Reason for a registered claim or `typ` header that is missing, malformed,
+ * different from the expected value, or outside its validity window.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class ClaimValidationFailed extends Data.TaggedError("ClaimValidationFailed")<{
+  readonly claim: "iss" | "sub" | "aud" | "exp" | "nbf" | "iat" | "jti" | "typ"
+  readonly reason: "invalid" | "missing" | "mismatch" | "expired" | "notYetValid" | "tooOld" | "future"
+}> {
+  /**
+   * Marks this value as a `JoseError` reason for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [ReasonTypeId] = ReasonTypeId
+
+  override get message(): string {
+    return `The ${this.claim} claim failed validation: ${this.reason}`
+  }
+}
+
+/**
+ * Union of the reasons carried by `JoseError`.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export type JoseErrorReason =
+  | InvalidToken
+  | InvalidKey
+  | InvalidArgument
+  | AlgorithmNotAllowed
+  | SignatureVerificationFailed
+  | DecryptionFailed
+  | KeyNotFound
+  | AmbiguousKey
+  | KeySetUnavailable
+  | ClaimValidationFailed
+
+/**
+ * Error returned by the `effect/jose` modules.
+ *
+ * **Example** (Rejecting a token with a bad signature)
+ *
+ * ```ts import.meta.vitest
+ * 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"
+ * ```
+ *
+ * @see {@link isJoseError} for narrowing unknown values
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.1
+ */
+export class JoseError extends Data.TaggedError("JoseError")<{
+  readonly reason: JoseErrorReason
+}> {
+  /**
+   * Marks this value as a `JoseError` for runtime guards.
+   *
+   * @since 4.1.1
+   */
+  readonly [TypeId] = TypeId
+
+  /**
+   * The reason's cause, when it has one.
+   *
+   * @since 4.1.1
+   */
+  override readonly cause: unknown = "cause" in this.reason ? this.reason.cause : undefined
+
+  override get message(): string {
+    return this.reason.message
+  }
+}
+
+/**
+ * Checks whether a value is a `JoseError`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.1.1
+ */
+export const isJoseError = (u: unknown): u is JoseError => Predicate.hasProperty(u, TypeId)
+
+/**
+ * Checks whether a value is one of the reasons carried by `JoseError`.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.1.1
+ */
+export const isJoseErrorReason = (u: unknown): u is JoseErrorReason => Predicate.hasProperty(u, ReasonTypeId)

package/src/jose/Jwe.ts

@@ -0,0 +1,196 @@
+/**
+ * Compact JSON Web Encryption with a shared key: `dir` key management and
+ * A256GCM content encryption.
+ *
+ * The protected header is authenticated as additional data, so changing it
+ * fails decryption. Headers with `crit` or `zip` are rejected.
+ *
+ * Bound untrusted token length before decryption; this module does not impose
+ * a token-size limit.
+ *
+ * @stability unstable
+ * @since 4.1.1
+ */
+import * as Aead from "../crypto/Aead.ts"
+import * as SecureRandom from "../crypto/SecureRandom.ts"
+import * as Effect from "../Effect.ts"
+import * as Base64Url from "../encoding/Base64Url.ts"
+import * as Redacted from "../Redacted.ts"
+import * as Schema from "../Schema.ts"
+import {
+  cryptoFailure,
+  decodeHeader,
+  decodeSegment,
+  encodeHeader,
+  invalidToken,
+  split,
+  utf8
+} from "./internal/compact.ts"
+import * as JoseError from "./JoseError.ts"
+import type { SecretKey } from "./Jwk.ts"
+
+/**
+ * Schema for a JWE protected header, including additional JSON-valued
+ * parameters.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.1.1
+ */
+export const ProtectedHeader = Schema.StructWithRest(
+  Schema.Struct({
+    alg: Schema.Literal("dir"),
+    enc: Schema.Literal("A256GCM"),
+    kid: Schema.optionalKey(Schema.String),
+    typ: Schema.optionalKey(Schema.String),
+    cty: Schema.optionalKey(Schema.String)
+  }),
+  [Schema.Record(Schema.String, Schema.Json)]
+)
+
+/**
+ * A JWE protected header. It is authenticated only after decryption succeeds.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.1.1
+ */
+export type ProtectedHeader = typeof ProtectedHeader.Type
+
+/**
+ * Standard header parameters to protect. Encryption also accepts additional
+ * JSON-valued parameters. `alg` and `enc` are fixed and `kid` defaults to the
+ * key's.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.1.1
+ */
+export interface Header {
+  readonly alg?: never
+  readonly enc?: never
+  readonly crit?: never
+  readonly zip?: never
+  readonly kid?: string | undefined
+  readonly typ?: string | undefined
+  readonly cty?: string | undefined
+}
+
+/**
+ * The protected header, plaintext, and key used to decrypt a JWE.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.1.1
+ */
+export interface Decrypted {
+  readonly protectedHeader: ProtectedHeader
+  readonly plaintext: Uint8Array
+  readonly key: SecretKey<"dir">
+}
+
+const tagLength = 16
+
+const decodeProtectedHeader = Schema.decodeUnknownOption(ProtectedHeader)
+
+/**
+ * Encrypts plaintext as a compact JWE with a random 96-bit IV.
+ *
+ * **Example** (Encrypting and decrypting a message)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer, Redacted } from "effect"
+ * import { Aead, SecureRandom } from "effect/crypto"
+ * import { Jwe, Jwk } from "effect/jose"
+ *
+ * const layer = Aead.layerWebCrypto.pipe(Layer.provideMerge(SecureRandom.layerWebCrypto))
+ *
+ * const plaintext = await Effect.runPromise(Effect.gen(function*() {
+ *   // Fixed public example material; generate application secrets securely.
+ *   const key = yield* Jwk.importSecret(
+ *     Redacted.make({ kty: "oct", k: "BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc" } as const),
+ *     "dir"
+ *   )
+ *   const token = yield* Jwe.encrypt(new TextEncoder().encode("private message"), key)
+ *   const decrypted = yield* Jwe.decrypt(token, key)
+ *   return new TextDecoder().decode(decrypted.plaintext)
+ * }).pipe(Effect.provide(layer)))
+ * plaintext // => "private message"
+ * ```
+ *
+ * @see {@link decrypt}
+ *
+ * @stability unstable
+ * @category cryptography
+ * @since 4.1.1
+ */
+export const encrypt = Effect.fnUntraced(function*<
+  H extends object & { readonly [P in keyof H]: Schema.Json | undefined } = Header
+>(
+  plaintext: Uint8Array,
+  key: SecretKey<"dir">,
+  header?: Header & H
+): Effect.fn.Return<Redacted.Redacted<string>, JoseError.JoseError, Aead.Aead | SecureRandom.SecureRandom> {
+  const protectedHeader = yield* encodeHeader({ alg: "dir", enc: "A256GCM" }, key.kid, header, ["crit", "zip"])
+  const random = yield* SecureRandom.SecureRandom
+  const aead = yield* Aead.Aead
+  const nonce = yield* random.randomBytes(Aead.aes256Gcm.nonceLength)
+  const sealed = yield* aead.encrypt(key.key, plaintext, { nonce, aad: utf8(protectedHeader) }).pipe(
+    Effect.mapError(cryptoFailure("Could not encrypt with the key"))
+  )
+  const ciphertext = Base64Url.encode(sealed.subarray(0, -tagLength))
+  const tag = Base64Url.encode(sealed.subarray(-tagLength))
+  return Redacted.make(`${protectedHeader}..${Base64Url.encode(nonce)}.${ciphertext}.${tag}`)
+})
+
+/**
+ * Decrypts a compact `dir`/A256GCM JWE and authenticates its protected
+ * header.
+ *
+ * **Details**
+ *
+ * Accepts a key or an effectful resolver for key rotation. The token's
+ * structure and supported header parameters are checked before the resolver
+ * runs. Resolver failures and service requirements are preserved.
+ *
+ * **Gotchas**
+ *
+ * The resolver receives an unauthenticated header and must use it only for
+ * key selection.
+ *
+ * @see {@link encrypt}
+ *
+ * @stability unstable
+ * @category cryptography
+ * @since 4.1.1
+ */
+export const decrypt = Effect.fnUntraced(function*<E = never, R = never>(
+  token: string | Redacted.Redacted<string>,
+  key: SecretKey<"dir"> | ((header: ProtectedHeader) => Effect.Effect<SecretKey<"dir">, E, R>)
+): Effect.fn.Return<Decrypted, JoseError.JoseError | E, Aead.Aead | R> {
+  const [header, encryptedKey, iv, ciphertext, tag] = yield* split(token, 5)
+  if (encryptedKey !== "") return yield* invalidToken("A dir token must have an empty encrypted key")
+  const protectedHeader = yield* decodeHeader(header, decodeProtectedHeader, ["crit", "zip"])
+  const nonce = decodeSegment(iv)
+  const data = decodeSegment(ciphertext)
+  const authTag = decodeSegment(tag)
+  if (
+    nonce === undefined || data === undefined || authTag === undefined ||
+    nonce.length !== Aead.aes256Gcm.nonceLength || authTag.length !== tagLength
+  ) {
+    return yield* invalidToken("The IV, ciphertext, or tag is malformed")
+  }
+  const resolvedKey = typeof key === "function" ? yield* key(protectedHeader) : key
+  const sealed = new Uint8Array(data.length + tagLength)
+  sealed.set(data)
+  sealed.set(authTag, data.length)
+  const aead = yield* Aead.Aead
+  const plaintext = yield* aead.decrypt(resolvedKey.key, sealed, { nonce, aad: utf8(header) }).pipe(
+    Effect.mapError((error) =>
+      error.reason._tag === "DecryptionFailed"
+        ? new JoseError.JoseError({ reason: new JoseError.DecryptionFailed() })
+        : cryptoFailure("Could not decrypt with the key")(error)
+    )
+  )
+  return { protectedHeader, plaintext, key: resolvedKey }
+})