@yielded/jose 0.1.0-beta.19

package/src/Jwt.ts

@@ -0,0 +1,187 @@
+import type { Signature } from "@yielded/crypto/Signature";
+import { Clock, Effect, Redacted, Schema } from "effect";
+
+import { ClaimValidationFailed, type VerifyError } from "./Errors";
+import {
+  decode,
+  json,
+  JsonObject,
+  parse,
+  reveal,
+  split,
+  stringify,
+  utf8,
+} from "./internal/encoding";
+import type { SigningKey, VerificationKey } from "./Jwk";
+import type { Jwks } from "./Jwks";
+import { type Header, type Requirements, VerifyOptions as JwsVerifyOptions } from "./Jws";
+import * as Jws from "./Jws";
+
+export const RegisteredClaims = Schema.Struct({
+  iss: Schema.optionalKey(Schema.String),
+  sub: Schema.optionalKey(Schema.String),
+  aud: Schema.optionalKey(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
+  exp: Schema.optionalKey(Schema.Finite),
+  nbf: Schema.optionalKey(Schema.Finite),
+  iat: Schema.optionalKey(Schema.Finite),
+  jti: Schema.optionalKey(Schema.String),
+});
+
+export type RegisteredClaims = typeof RegisteredClaims.Type;
+
+const expected = Schema.Union([
+  Schema.String,
+  Schema.Array(Schema.String).check(Schema.isMinLength(1)),
+]);
+
+const seconds = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+
+export const VerifyOptions = Schema.Struct({
+  ...JwsVerifyOptions.fields,
+  issuer: Schema.optionalKey(expected),
+  audience: Schema.optionalKey(expected),
+  subject: Schema.optionalKey(Schema.String),
+  typ: Schema.optionalKey(Schema.NonEmptyString),
+  clockTolerance: Schema.optionalKey(seconds),
+  maxTokenAge: Schema.optionalKey(seconds),
+  requiredClaims: Schema.optionalKey(
+    Schema.Array(Schema.Literals(["iss", "sub", "aud", "exp", "nbf", "iat", "jti"])),
+  ),
+});
+
+export type VerifyOptions = typeof VerifyOptions.Type;
+
+export interface Verified<A> {
+  readonly claims: A;
+  readonly registeredClaims: RegisteredClaims;
+  readonly protectedHeader: Header;
+}
+
+export type JwtError = VerifyError | ClaimValidationFailed | Schema.SchemaError;
+
+const checkClaims = Effect.fnUntraced(function* (
+  claims: Readonly<Record<string, Schema.Json>>,
+  header: Header,
+  options: VerifyOptions,
+) {
+  const registered = yield* Schema.decodeUnknownEffect(RegisteredClaims)(claims, {
+    reportInput: false,
+  }).pipe(
+    Effect.mapError(() => ClaimValidationFailed.make({ claim: "registered", reason: "invalid" })),
+  );
+
+  for (const claim of options.requiredClaims ?? []) {
+    if (registered[claim] === undefined)
+      return yield* ClaimValidationFailed.make({ claim, reason: "missing" });
+  }
+  if (options.issuer !== undefined) {
+    if (registered.iss === undefined)
+      return yield* ClaimValidationFailed.make({ claim: "iss", reason: "missing" });
+    const expected = typeof options.issuer === "string" ? [options.issuer] : options.issuer;
+
+    if (!expected.includes(registered.iss))
+      return yield* ClaimValidationFailed.make({ claim: "iss", reason: "mismatch" });
+  }
+  if (options.subject !== undefined) {
+    if (registered.sub === undefined)
+      return yield* ClaimValidationFailed.make({ claim: "sub", reason: "missing" });
+    if (options.subject !== registered.sub)
+      return yield* ClaimValidationFailed.make({ claim: "sub", reason: "mismatch" });
+  }
+  if (options.audience !== undefined) {
+    if (registered.aud === undefined)
+      return yield* ClaimValidationFailed.make({ claim: "aud", reason: "missing" });
+    const expected = typeof options.audience === "string" ? [options.audience] : options.audience;
+    const actual = typeof registered.aud === "string" ? [registered.aud] : registered.aud;
+
+    if (!expected.some((audience) => actual.includes(audience)))
+      return yield* ClaimValidationFailed.make({ claim: "aud", reason: "mismatch" });
+  }
+
+  const normalizedType = (value: string) => {
+    const type = value.toLowerCase();
+
+    return type.includes("/") ? type : `application/${type}`;
+  };
+
+  if (
+    options.typ !== undefined &&
+    (header.typ === undefined || normalizedType(header.typ) !== normalizedType(options.typ))
+  )
+    return yield* ClaimValidationFailed.make({ claim: "typ", reason: "mismatch" });
+  const now = Math.floor((yield* Clock.currentTimeMillis) / 1000);
+  const tolerance = options.clockTolerance ?? 0;
+
+  if (registered.exp !== undefined && registered.exp <= now - tolerance)
+    return yield* ClaimValidationFailed.make({ claim: "exp", reason: "expired" });
+  if (registered.nbf !== undefined && registered.nbf > now + tolerance)
+    return yield* ClaimValidationFailed.make({ claim: "nbf", reason: "notYetValid" });
+  if (options.maxTokenAge !== undefined) {
+    if (registered.iat === undefined)
+      return yield* ClaimValidationFailed.make({ claim: "iat", reason: "missing" });
+    if (registered.iat > now + tolerance)
+      return yield* ClaimValidationFailed.make({ claim: "iat", reason: "future" });
+    if (now - registered.iat - tolerance > options.maxTokenAge)
+      return yield* ClaimValidationFailed.make({ claim: "iat", reason: "tooOld" });
+  }
+
+  return registered;
+});
+
+const decodeClaims = Effect.fnUntraced(function* <S extends Schema.Constraint>(
+  schema: S,
+  verified: Jws.Verified,
+  options: VerifyOptions,
+) {
+  const wire = yield* json(yield* reveal(verified.payload), "payload");
+  const registeredClaims = yield* checkClaims(wire, verified.protectedHeader, options);
+  const claims = yield* Schema.decodeUnknownEffect(schema)(wire, { reportInput: false });
+
+  return { claims, registeredClaims, protectedHeader: verified.protectedHeader } satisfies Verified<
+    S["Type"]
+  >;
+});
+
+export const sign = Effect.fnUntraced(function* <S extends Schema.Constraint>(
+  schema: S,
+  claims: S["Type"],
+  key: SigningKey,
+  header: Header,
+): Effect.fn.Return<Redacted.Redacted<string>, JwtError, Requirements | S["EncodingServices"]> {
+  const encoded = yield* Schema.encodeEffect(schema)(claims, { reportInput: false });
+  const wire = yield* Schema.decodeUnknownEffect(JsonObject)(encoded, { reportInput: false });
+
+  yield* Schema.decodeUnknownEffect(RegisteredClaims)(wire, { reportInput: false });
+
+  return yield* Jws.sign(Redacted.make(utf8(yield* stringify(wire))), key, header);
+});
+
+export const verify = Effect.fnUntraced(function* <S extends Schema.Constraint>(
+  schema: S,
+  token: Redacted.Redacted<string>,
+  key: VerificationKey,
+  options: VerifyOptions,
+): Effect.fn.Return<Verified<S["Type"]>, JwtError, Requirements | S["DecodingServices"]> {
+  // Capture all policy before asynchronous cryptography or key resolution.
+  const policy = yield* parse(VerifyOptions, options, "parameters");
+
+  return yield* decodeClaims(schema, yield* Jws.verify(token, key, policy), policy);
+});
+
+export const verifyWithKeySet = Effect.fnUntraced(function* <S extends Schema.Constraint>(
+  schema: S,
+  token: Redacted.Redacted<string>,
+  options: VerifyOptions,
+): Effect.fn.Return<Verified<S["Type"]>, JwtError, Signature | Jwks | S["DecodingServices"]> {
+  const policy = yield* parse(VerifyOptions, options, "parameters");
+
+  return yield* decodeClaims(schema, yield* Jws.verifyWithKeySet(token, policy), policy);
+});
+
+/** Parsing only. This result does not establish authenticity or validate claims. */
+export const decodeUnverified = Effect.fnUntraced(function* (token: Redacted.Redacted<string>) {
+  const [, payload] = yield* split(token, 3);
+  const claims = yield* json(yield* decode(payload), "payload");
+
+  return { _tag: "UnverifiedJwt", claims: Redacted.make(claims) } as const;
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+export * as Errors from "./Errors.ts";
+export * as Jwk from "./Jwk.ts";
+export * as Jwks from "./Jwks.ts";
+export * as Jws from "./Jws.ts";
+export * as Jwt from "./Jwt.ts";
+export * as Jwe from "./Jwe.ts";

package/src/internal/algorithms.ts

@@ -0,0 +1,10 @@
+import type { Algorithm } from "@yielded/crypto/Signature";
+
+import type { AsymmetricAlgorithm } from "../Jwk";
+
+export const algorithms = {
+  ES256: "ECDSA-P256-SHA256",
+  RS256: "RSASSA-PKCS1-v1_5-SHA256",
+  PS256: "RSA-PSS-SHA256",
+  EdDSA: "Ed25519",
+} satisfies Record<AsymmetricAlgorithm, Algorithm>;

package/src/internal/encoding.ts

@@ -0,0 +1,72 @@
+import { Effect, Redacted, Result, Schema } from "effect";
+import { Base64Url } from "effect/encoding";
+
+import { InvalidToken } from "../Errors";
+
+export const JsonObject = Schema.Record(Schema.String, Schema.Json);
+export const utf8 = (value: string) => new TextEncoder().encode(value);
+
+const Segment = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9_-]*$/),
+  Schema.isMaxLength(65536),
+);
+
+const Token = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(65536));
+
+export const parse = <S extends Schema.Constraint>(
+  schema: S,
+  input: unknown,
+  reason: InvalidToken["reason"],
+) =>
+  Effect.suspend(() => Schema.decodeUnknownEffect(schema)(input, { reportInput: false })).pipe(
+    Effect.mapError(() => InvalidToken.make({ reason })),
+    // Arbitrary nested input can still invoke foreign getters during decoding.
+    Effect.catchDefect(() => InvalidToken.make({ reason })),
+  );
+
+export const reveal = <A>(value: Redacted.Redacted<A>) =>
+  Effect.try({
+    try: () => Redacted.value(value),
+    catch: () => InvalidToken.make({ reason: "parameters" }),
+  });
+
+export const decode = Effect.fnUntraced(function* (
+  value: string,
+  reason: InvalidToken["reason"] = "serialization",
+) {
+  yield* parse(Segment, value, reason);
+
+  const bytes = yield* Result.match(Base64Url.decode(value), {
+    onFailure: () => Effect.fail(InvalidToken.make({ reason })),
+    onSuccess: Effect.succeed,
+  });
+
+  // Canonical, unpadded base64url also rejects non-zero unused bits.
+  if (Base64Url.encode(bytes) !== value) return yield* InvalidToken.make({ reason });
+
+  return bytes;
+});
+
+export const json = Effect.fnUntraced(function* (
+  bytes: Uint8Array,
+  reason: InvalidToken["reason"],
+) {
+  const value = yield* Effect.try({
+    try: () => new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    catch: () => InvalidToken.make({ reason }),
+  });
+
+  return yield* parse(Schema.fromJsonString(JsonObject), value, reason);
+});
+
+export const stringify = (value: Readonly<Record<string, Schema.Json>>) =>
+  Schema.encodeEffect(Schema.fromJsonString(JsonObject))(value, { reportInput: false });
+
+export const split = Effect.fnUntraced(function* (input: Redacted.Redacted<string>, count: number) {
+  const value = yield* parse(Token, yield* reveal(input), "serialization");
+  const parts = value.split(".");
+
+  if (parts.length !== count) return yield* InvalidToken.make({ reason: "serialization" });
+
+  return parts;
+});

package/src/internal/keyInput.ts

@@ -0,0 +1,75 @@
+import { Predicate, Result, Schema } from "effect";
+
+import { InvalidKey } from "../Errors";
+
+export const maxArrayLength = 256;
+
+const ArrayLength = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: maxArrayLength }));
+
+/** Copy only own fields, evaluating accessors once before Schema validation. */
+export const object = (input: unknown): unknown => {
+  if (!Predicate.isObject(input)) return input;
+  const descriptors = Object.getOwnPropertyDescriptors(input);
+  const copy: Record<string, unknown> = {};
+
+  Object.setPrototypeOf(copy, null);
+  for (const name of Object.getOwnPropertyNames(descriptors)) {
+    const descriptor = descriptors[name];
+
+    copy[name] = Object.hasOwn(descriptor, "value")
+      ? descriptor.value
+      : descriptor.get?.call(input);
+  }
+
+  return copy;
+};
+
+const array = (input: ReadonlyArray<unknown>) =>
+  Result.gen(function* () {
+    const length = yield* Schema.decodeUnknownResult(ArrayLength)(input.length).pipe(
+      Result.mapError(() => InvalidKey.make({})),
+    );
+
+    // Capture bounded own slots before any accessor can mutate the array.
+    const descriptors = Array.from({ length }, (_, index) =>
+      Object.getOwnPropertyDescriptor(input, index),
+    );
+
+    return descriptors.map((descriptor) =>
+      descriptor === undefined
+        ? undefined
+        : Object.hasOwn(descriptor, "value")
+          ? descriptor.value
+          : descriptor.get?.call(input),
+    );
+  });
+
+export const jwk = (input: unknown) =>
+  Result.gen(function* () {
+    const copy = object(input);
+
+    if (Predicate.isObject(copy) && Array.isArray(copy.key_ops))
+      copy.key_ops = yield* array(copy.key_ops);
+
+    return copy;
+  });
+
+export const keySet = (input: unknown) =>
+  Result.gen(function* () {
+    const copy = object(input);
+
+    if (Predicate.isObject(copy) && Array.isArray(copy.keys)) {
+      const keys = yield* array(copy.keys);
+
+      copy.keys = yield* Result.all(keys.map(jwk));
+    }
+
+    return copy;
+  });
+
+/** Struct decoding creates ordinary objects; detach owned output as well. */
+export const detach = <A>(value: A): A => {
+  if (Predicate.isObject(value)) Object.setPrototypeOf(value, null);
+
+  return value;
+};

package/src/internal/keyPolicy.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+
+import { InvalidKey } from "../Errors";
+import type { PrivateJwk, PublicJwk, SecretJwk } from "../Jwk";
+
+export const check = (
+  jwk: PublicJwk | PrivateJwk | SecretJwk,
+  algorithm: string,
+  operation: "sign" | "verify" | "encrypt" | "decrypt",
+) => {
+  const use = operation === "sign" || operation === "verify" ? "sig" : "enc";
+
+  return (jwk.alg !== undefined && jwk.alg !== algorithm) ||
+    (jwk.use !== undefined && jwk.use !== use) ||
+    (jwk.key_ops !== undefined && !jwk.key_ops.includes(operation))
+    ? Effect.fail(InvalidKey.make({}))
+    : Effect.void;
+};