@yielded/oauth 0.1.0-beta.19

package/src/Errors.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+
+/** Local protocol configuration is invalid; no remote response or credential is retained. */
+export class ConfigurationError extends Schema.TaggedError<ConfigurationError>()(
+  "OAuthConfigurationError",
+  {
+    reason: Schema.Literals(["issuer", "metadata", "authentication", "parameters", "endpoint"]),
+  },
+) {}
+
+/** A definite, authenticated claim rejection or a complete HTTP 400 invalid_grant. */
+export class Rejected extends Schema.TaggedError<Rejected>()("OAuthRejected", {
+  reason: Schema.Literals(["invalid_grant", "claims"]),
+}) {}
+
+/** The outcome is unknown. This error never authorizes retrying a grant. */
+export class Unavailable extends Schema.TaggedError<Unavailable>()("OAuthUnavailable", {}) {}

package/src/OAuth.ts

@@ -0,0 +1,463 @@
+import { Effect, Redacted, Schema, type Scope } from "effect";
+import { Base64 } from "effect/encoding";
+import type { HttpClient } from "effect/http";
+import { HttpClientRequest } from "effect/http";
+
+import { ConfigurationError, Rejected, Unavailable } from "./Errors";
+import * as Ownership from "./internal/ownership";
+import * as Transport from "./internal/transport";
+import * as V from "./internal/validation";
+
+export const JsonObject = V.JsonObject;
+export type JsonObject = typeof JsonObject.Type;
+
+export const Metadata = Schema.Struct({
+  issuer: V.Issuer,
+  authorization_endpoint: V.ProtocolEndpoint,
+  token_endpoint: V.ProtocolEndpoint,
+  jwks_uri: Schema.optionalKey(V.Endpoint),
+  userinfo_endpoint: Schema.optionalKey(V.Endpoint),
+  revocation_endpoint: Schema.optionalKey(V.ProtocolEndpoint),
+  code_challenge_methods_supported: Schema.optionalKey(
+    Schema.Array(V.text(64)).check(Schema.isMaxLength(64)),
+  ),
+  response_types_supported: Schema.optionalKey(
+    Schema.Array(V.text(64)).check(Schema.isMaxLength(64)),
+  ),
+  grant_types_supported: Schema.optionalKey(
+    Schema.Array(V.text(128)).check(Schema.isMaxLength(64)),
+  ),
+  id_token_signing_alg_values_supported: Schema.optionalKey(
+    Schema.Array(V.text(64)).check(Schema.isMaxLength(64)),
+  ),
+  token_endpoint_auth_methods_supported: Schema.optionalKey(
+    Schema.Array(V.text(64)).check(Schema.isMaxLength(64)),
+  ),
+  revocation_endpoint_auth_methods_supported: Schema.optionalKey(
+    Schema.Array(V.text(64)).check(Schema.isMaxLength(64)),
+  ),
+  authorization_response_iss_parameter_supported: Schema.optionalKey(Schema.Boolean),
+});
+
+export type Metadata = typeof Metadata.Type;
+
+export const Authentication = Schema.Union([
+  Schema.Struct({ method: Schema.Literal("client_secret_basic"), secret: V.secret(4096) }),
+  Schema.Struct({ method: Schema.Literal("client_secret_post"), secret: V.secret(4096) }),
+  Schema.Struct({ method: Schema.Literal("none"), publicClient: Schema.Literal(true) }),
+]);
+
+export type Authentication = typeof Authentication.Type;
+
+/** Uninterpreted private receipt. Inspect provider extensions before calling tokens. */
+export const TokenReceipt = Schema.Struct({
+  status: V.integer(100, 599),
+  contentType: Schema.NullOr(Schema.String.check(Schema.isMaxLength(512))),
+  body: Schema.Redacted(JsonObject, { disallowJsonEncode: true }),
+});
+
+export type TokenReceipt = typeof TokenReceipt.Type;
+
+export const TokenSet = Schema.Struct({
+  tokenType: Schema.Literal("bearer"),
+  accessToken: V.secret(16384),
+  refreshToken: Schema.optionalKey(V.secret(16384)),
+  idToken: Schema.optionalKey(V.secret(65536)),
+  expiresIn: Schema.optionalKey(Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0))),
+  scope: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(16447))),
+});
+
+export type TokenSet = typeof TokenSet.Type;
+
+export interface RequestOptions {
+  readonly timeoutMs: number;
+  readonly maxResponseBytes?: number;
+}
+
+export interface ClientOptions extends RequestOptions {
+  readonly metadata: Metadata;
+  readonly clientId: string;
+  readonly authentication: Authentication;
+  readonly profile?: { readonly url: string; readonly headers?: Readonly<Record<string, string>> };
+  readonly revocationAuthentication?: Authentication;
+}
+
+export interface Parameters {
+  readonly parameters?: Readonly<Record<string, string>>;
+  readonly resources?: ReadonlyArray<string>;
+}
+
+export interface AuthorizationInput extends Parameters {
+  readonly redirectUri: string;
+  readonly scopes: ReadonlyArray<string>;
+  readonly state: Redacted.Redacted<string>;
+  readonly codeChallenge: string;
+  readonly nonce?: Redacted.Redacted<string>;
+  readonly maxAgeSeconds?: number;
+}
+
+export interface CodeGrantInput extends Parameters {
+  readonly code: Redacted.Redacted<string>;
+  readonly redirectUri: string;
+  readonly pkceVerifier: Redacted.Redacted<string>;
+}
+
+export interface RefreshGrantInput extends Parameters {
+  readonly refreshToken: Redacted.Redacted<string>;
+  readonly scopes?: ReadonlyArray<string>;
+}
+
+export interface RevocationInput {
+  readonly token: Redacted.Redacted<string>;
+  readonly tokenTypeHint: "access_token" | "refresh_token";
+}
+
+export interface Client {
+  readonly metadata: Metadata;
+  readonly authorizationUrl: (
+    input: AuthorizationInput,
+  ) => Effect.Effect<Redacted.Redacted<string>, ConfigurationError | Unavailable>;
+  readonly codeGrant: (
+    input: CodeGrantInput,
+  ) => Effect.Effect<TokenReceipt, ConfigurationError | Unavailable>;
+  readonly refreshGrant: (
+    input: RefreshGrantInput,
+  ) => Effect.Effect<TokenReceipt, ConfigurationError | Unavailable>;
+  readonly fetchProfile: (
+    accessToken: Redacted.Redacted<string>,
+  ) => Effect.Effect<JsonObject, ConfigurationError | Unavailable>;
+  readonly revoke: (
+    input: RevocationInput,
+  ) => Effect.Effect<void, ConfigurationError | Unavailable>;
+}
+
+const ClientOptionsSchema = Schema.Struct({
+  metadata: Metadata,
+  clientId: V.text(1024),
+  authentication: Authentication,
+  ...V.RequestOptions.fields,
+  profile: Schema.optionalKey(
+    Schema.Struct({ url: V.Endpoint, headers: Schema.optionalKey(V.Headers) }),
+  ),
+  revocationAuthentication: Schema.optionalKey(Authentication),
+});
+
+const additional = {
+  parameters: Schema.optionalKey(V.Parameters),
+  resources: Schema.optionalKey(V.Resources),
+};
+
+const Authorization = Schema.Struct({
+  ...additional,
+  redirectUri: V.Callback,
+  scopes: V.Scopes,
+  state: V.secret(256),
+  codeChallenge: V.Challenge,
+  nonce: Schema.optionalKey(V.secret(256)),
+  maxAgeSeconds: Schema.optionalKey(V.integer(0, 86400)),
+});
+
+const CodeGrant = Schema.Struct({
+  ...additional,
+  code: V.secret(16384),
+  redirectUri: V.Callback,
+  pkceVerifier: V.Verifier,
+});
+
+const RefreshGrant = Schema.Struct({
+  ...additional,
+  refreshToken: V.secret(16384),
+  scopes: Schema.optionalKey(V.Scopes),
+});
+
+const Revocation = Schema.Struct({
+  token: V.secret(16384),
+  tokenTypeHint: Schema.Literals(["access_token", "refresh_token"]),
+});
+
+const ExpiresIn = Schema.Union([
+  Schema.Finite,
+  Schema.String.check(Schema.isPattern(/^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u)).pipe(
+    Schema.decodeTo(Schema.FiniteFromString),
+  ),
+]).check(Schema.isGreaterThanOrEqualTo(0));
+
+const RawToken = Schema.Struct({
+  access_token: V.text(16384),
+  token_type: Schema.String.check(Schema.isPattern(/^[Bb][Ee][Aa][Rr][Ee][Rr]$/)),
+  refresh_token: Schema.optionalKey(V.text(16384)),
+  id_token: Schema.optionalKey(V.text(65536)),
+  expires_in: Schema.optionalKey(ExpiresIn),
+  scope: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(16447))),
+});
+
+const Terminal = Schema.Struct({
+  error: V.text(128),
+  error_description: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(4096))),
+  error_uri: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(2048))),
+});
+
+const successFields = [
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "token_type",
+  "scope",
+  "expires_in",
+  "refresh_expires_in",
+  "refresh_token_expires_in",
+];
+
+/** Parse once provider-specific receipt checks have succeeded. expires_in accepts
+ * finite nonnegative numbers and whole decimal strings (for example "60.5").
+ * Whitespace, exponent/prefix syntax and nonfinite values are rejected. Raw
+ * receipt extensions/scopes are untouched; no request, retry or claim verification. */
+export const tokens = Effect.fnUntraced(function* (
+  input: TokenReceipt,
+): Effect.fn.Return<TokenSet, Rejected | Unavailable> {
+  const receipt = yield* V.decode(TokenReceipt, input);
+
+  if (!Transport.isJson(receipt.contentType)) return yield* Unavailable.make({});
+  const raw = yield* V.reveal(receipt.body);
+
+  if (Object.hasOwn(raw, "error")) {
+    if (successFields.some((key) => Object.hasOwn(raw, key))) return yield* Unavailable.make({});
+    const terminal = yield* V.decode(Terminal, raw);
+
+    if (receipt.status === 400 && terminal.error === "invalid_grant")
+      return yield* Rejected.make({ reason: "invalid_grant" });
+
+    return yield* Unavailable.make({});
+  }
+  if (
+    receipt.status !== 200 ||
+    Object.hasOwn(raw, "error_description") ||
+    Object.hasOwn(raw, "error_uri")
+  )
+    return yield* Unavailable.make({});
+  const value = yield* V.decode(RawToken, raw);
+
+  return {
+    tokenType: "bearer",
+    accessToken: Redacted.make(value.access_token),
+    ...(value.refresh_token === undefined
+      ? {}
+      : { refreshToken: Redacted.make(value.refresh_token) }),
+    ...(value.id_token === undefined ? {} : { idToken: Redacted.make(value.id_token) }),
+    ...(value.expires_in === undefined ? {} : { expiresIn: value.expires_in }),
+    ...(value.scope === undefined ? {} : { scope: value.scope }),
+  };
+});
+
+const parameters = (input: Parameters) => {
+  const values = new URLSearchParams(input.parameters);
+
+  for (const resource of input.resources ?? []) values.append("resource", resource);
+
+  return values;
+};
+
+// RFC6749 Appendix B: encode client credentials before joining with the colon.
+// Adapted from oauth4webapi 3.8.8 src/index.ts::formUrlEncode (MIT, Filip Skokan).
+// Exact source commit and license: ../THIRD_PARTY_NOTICES.md.
+const basicComponent = (value: string) =>
+  encodeURIComponent(value).replace(/[-_.!~*'()]|%20/gu, (part) =>
+    part === "%20" ? "+" : `%${part.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+
+const authenticated = Effect.fnUntraced(function* (
+  url: string,
+  clientId: string,
+  authentication: Authentication,
+  body: URLSearchParams,
+) {
+  let request = HttpClientRequest.post(url).pipe(HttpClientRequest.acceptJson);
+
+  if (authentication.method === "client_secret_basic") {
+    const secret = yield* V.reveal(authentication.secret);
+
+    const credential = yield* Effect.try({
+      try: () => Base64.encode(`${basicComponent(clientId)}:${basicComponent(secret)}`),
+      catch: () => Unavailable.make({}),
+    });
+
+    request = HttpClientRequest.setHeader(request, "authorization", `Basic ${credential}`);
+  } else {
+    body.set("client_id", clientId);
+    if (authentication.method === "client_secret_post")
+      body.set("client_secret", yield* V.reveal(authentication.secret));
+  }
+  const encoded = body.toString();
+
+  if (new TextEncoder().encode(encoded).length > 131072)
+    return yield* ConfigurationError.make({ reason: "parameters" });
+
+  return HttpClientRequest.bodyText(
+    request,
+    encoded,
+    "application/x-www-form-urlencoded;charset=UTF-8",
+  );
+});
+
+/** One installed client, exact endpoints, private credentials and owning Scope.
+ * Supply an HttpClient without retry/redirect/cookie middleware. Fetch injection
+ * active at construction is captured. Owner closure cancels and joins active
+ * operations, then rejects their results as unavailable; caller interruption
+ * cancels and joins its operation without closing the client. */
+export const make = Effect.fnUntraced(function* (
+  input: ClientOptions,
+): Effect.fn.Return<Client, ConfigurationError | Unavailable, HttpClient.HttpClient | Scope.Scope> {
+  const options = yield* V.configuration(ClientOptionsSchema, input, "metadata");
+
+  const authentication = yield* detachAuthentication(options.authentication);
+
+  const revocationAuthentication =
+    options.revocationAuthentication === undefined
+      ? authentication
+      : yield* detachAuthentication(options.revocationAuthentication);
+
+  const metadata = V.freeze(options.metadata);
+
+  const supported =
+    metadata.token_endpoint_auth_methods_supported ??
+    (metadata.jwks_uri === undefined ? undefined : ["client_secret_basic"]);
+
+  const revokeSupported =
+    metadata.revocation_endpoint_auth_methods_supported ??
+    (metadata.jwks_uri === undefined ? undefined : ["client_secret_basic"]);
+
+  if (
+    (supported !== undefined && !supported.includes(authentication.method)) ||
+    (options.revocationAuthentication !== undefined &&
+      metadata.revocation_endpoint !== undefined &&
+      revokeSupported !== undefined &&
+      !revokeSupported.includes(revocationAuthentication.method))
+  )
+    return yield* ConfigurationError.make({ reason: "authentication" });
+  const { available, use } = yield* Ownership.make;
+  const http = yield* Transport.capture;
+  const profile = options.profile === undefined ? undefined : V.freeze(options.profile);
+
+  yield* Effect.addFinalizer(() =>
+    Effect.sync(() => {
+      if (authentication.method !== "none") Redacted.wipeUnsafe(authentication.secret);
+      if (revocationAuthentication.method !== "none")
+        Redacted.wipeUnsafe(revocationAuthentication.secret);
+    }),
+  );
+
+  const send = Effect.fnUntraced(function* (body: URLSearchParams) {
+    yield* available;
+
+    const request = yield* authenticated(
+      new URL(metadata.token_endpoint).href,
+      options.clientId,
+      authentication,
+      body,
+    );
+
+    return yield* Transport.json(yield* Transport.request(http, request, options));
+  });
+
+  const authorizationUrl = Effect.fnUntraced(function* (input: AuthorizationInput) {
+    yield* available;
+    const value = yield* V.configuration(Authorization, input);
+    const url = new URL(metadata.authorization_endpoint);
+    const body = parameters(value);
+
+    body.set("client_id", options.clientId);
+    body.set("redirect_uri", value.redirectUri);
+    body.set("response_type", "code");
+    body.set("response_mode", "query");
+    body.set("scope", value.scopes.join(" "));
+    body.set("state", yield* V.reveal(value.state));
+    body.set("code_challenge", value.codeChallenge);
+    body.set("code_challenge_method", "S256");
+    if (value.nonce !== undefined) body.set("nonce", yield* V.reveal(value.nonce));
+    if (value.maxAgeSeconds !== undefined) body.set("max_age", String(value.maxAgeSeconds));
+    for (const [key, item] of body) url.searchParams.append(key, item);
+    if (url.href.length > 16384) return yield* ConfigurationError.make({ reason: "parameters" });
+
+    return Redacted.make(url.href);
+  }, use);
+
+  const codeGrant = Effect.fnUntraced(function* (input: CodeGrantInput) {
+    yield* available;
+    const value = yield* V.configuration(CodeGrant, input);
+    const body = parameters(value);
+
+    body.set("grant_type", "authorization_code");
+    body.set("code", yield* V.reveal(value.code));
+    body.set("code_verifier", yield* V.reveal(value.pkceVerifier));
+    body.set("redirect_uri", value.redirectUri);
+
+    return yield* send(body);
+  }, use);
+
+  const refreshGrant = Effect.fnUntraced(function* (input: RefreshGrantInput) {
+    yield* available;
+    const value = yield* V.configuration(RefreshGrant, input);
+    const body = parameters(value);
+
+    body.set("grant_type", "refresh_token");
+    body.set("refresh_token", yield* V.reveal(value.refreshToken));
+    if (value.scopes !== undefined) body.set("scope", value.scopes.join(" "));
+
+    return yield* send(body);
+  }, use);
+
+  const fetchProfile = Effect.fnUntraced(function* (input: Redacted.Redacted<string>) {
+    yield* available;
+    if (profile === undefined) return yield* ConfigurationError.make({ reason: "endpoint" });
+    const token = yield* V.reveal(yield* V.decode(Bearer, input));
+
+    const request = HttpClientRequest.get(new URL(profile.url).href).pipe(
+      HttpClientRequest.acceptJson,
+      HttpClientRequest.setHeaders(profile.headers ?? {}),
+      HttpClientRequest.setHeader("authorization", `Bearer ${token}`),
+    );
+
+    const response = yield* Transport.request(http, request, options);
+
+    if (response.status !== 200) return yield* Unavailable.make({});
+
+    return yield* V.reveal((yield* Transport.json(response)).body);
+  }, use);
+
+  const revoke = Effect.fnUntraced(function* (input: RevocationInput) {
+    yield* available;
+    if (metadata.revocation_endpoint === undefined)
+      return yield* ConfigurationError.make({ reason: "endpoint" });
+    if (revokeSupported !== undefined && !revokeSupported.includes(revocationAuthentication.method))
+      return yield* ConfigurationError.make({ reason: "authentication" });
+    const value = yield* V.configuration(Revocation, input);
+
+    const request = yield* authenticated(
+      new URL(metadata.revocation_endpoint).href,
+      options.clientId,
+      revocationAuthentication,
+      new URLSearchParams({
+        token: yield* V.reveal(value.token),
+        token_type_hint: value.tokenTypeHint,
+      }),
+    );
+
+    const response = yield* Transport.request(http, request, options);
+
+    if (response.status !== 200) return yield* Unavailable.make({});
+  }, use);
+
+  return { metadata, authorizationUrl, codeGrant, refreshGrant, fetchProfile, revoke };
+});
+
+const Bearer = Schema.Redacted(V.text(16384).check(Schema.isPattern(/^[A-Za-z0-9._~+/-]+=*$/u)), {
+  disallowJsonEncode: true,
+});
+
+const detachAuthentication = Effect.fnUntraced(function* (
+  authentication: Authentication,
+): Effect.fn.Return<Authentication, Unavailable> {
+  return authentication.method === "none"
+    ? { ...authentication }
+    : { ...authentication, secret: Redacted.make(yield* V.reveal(authentication.secret)) };
+});