@fluixi/oauth2 1.0.0-alpha.1

package/dist/pkce.cjs

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/pkce.ts
+var pkce_exports = {};
+__export(pkce_exports, {
+  claimsOf: () => claimsOf,
+  createChallenge: () => createChallenge,
+  createPkcePair: () => createPkcePair,
+  createStateValue: () => createStateValue,
+  createVerifier: () => createVerifier,
+  expiryFrom: () => expiryFrom,
+  expiryFromJwt: () => expiryFromJwt,
+  timingSafeEqual: () => timingSafeEqual
+});
+module.exports = __toCommonJS(pkce_exports);
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+function createVerifier() {
+  return base64url(randomBytes(32));
+}
+function createStateValue() {
+  return base64url(randomBytes(16));
+}
+async function createChallenge(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+async function createPkcePair() {
+  const verifier = createVerifier();
+  return { verifier, challenge: await createChallenge(verifier) };
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function expiryFrom(expiresIn, now = Date.now()) {
+  const seconds = typeof expiresIn === "number" ? expiresIn : Number(expiresIn);
+  return Number.isFinite(seconds) && seconds > 0 ? now + seconds * 1e3 : void 0;
+}
+function claimsOf(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    return JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, "=")));
+  } catch {
+    return null;
+  }
+}
+function expiryFromJwt(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const json = JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, "=")));
+    return typeof json.exp === "number" ? json.exp * 1e3 : null;
+  } catch {
+    return null;
+  }
+}

package/dist/pkce.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PKCE, and the random values the flow needs.
+ *
+ * A browser client cannot keep a secret, so the authorization code alone is not enough
+ * to prove the request came from the app that started it. PKCE closes that: the client
+ * invents a `code_verifier`, sends only its hash on the way out, and presents the
+ * original when exchanging the code. An attacker who intercepts the code has neither.
+ *
+ * `state` is the other half, and a different problem: it proves the callback belongs to
+ * a flow this client started, which is what stops a forged callback.
+ *
+ * Everything here goes through the Web Crypto API, which every browser with custom
+ * elements has, and which Node has had since 18.
+ */
+/** A `code_verifier`: 43 to 128 characters from the unreserved set. */
+export declare function createVerifier(): string;
+/** A `state` or `nonce`. Same shape, different job. */
+export declare function createStateValue(): string;
+/**
+ * The `code_challenge` for a verifier, as S256.
+ *
+ * The `plain` method is in the spec and is worth nothing: it sends the verifier itself.
+ * This package does not offer it.
+ */
+export declare function createChallenge(verifier: string): Promise<string>;
+/** A verifier with its challenge, which is how a caller always wants them. */
+export declare function createPkcePair(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+/**
+ * Compare two `state` values without leaking where they differ.
+ *
+ * The timing of a `===` on strings depends on the first differing character. That is a
+ * weak signal here, since state is single-use and short-lived, but comparing it properly
+ * costs nothing.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+/** Epoch milliseconds from an `expires_in` in seconds. */
+export declare function expiryFrom(expiresIn: unknown, now?: number): number | undefined;
+/**
+ * A JWT's payload, without verifying the signature.
+ *
+ * Legitimate for a token this client fetched itself: the code exchange is a direct TLS
+ * call to the token endpoint, so the response is authentic by transport, which is what
+ * OIDC allows a confidential exchange to rely on. Never use this on a token that arrived
+ * from somewhere else.
+ */
+export declare function claimsOf(token: string): Record<string, unknown> | null;
+/**
+ * The `exp` of a JWT, in epoch milliseconds.
+ *
+ * Reads the payload without verifying the signature, which is correct for this use: the
+ * client is deciding when to refresh, not whether to trust the token. The server that
+ * receives it verifies it properly.
+ */
+export declare function expiryFromJwt(token: string): number | null;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgBH,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvE;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAGvF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK7D;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAGnF;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAStE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY1D"}

package/dist/pkce.js

@@ -0,0 +1,112 @@
+/**
+ * PKCE, and the random values the flow needs.
+ *
+ * A browser client cannot keep a secret, so the authorization code alone is not enough
+ * to prove the request came from the app that started it. PKCE closes that: the client
+ * invents a `code_verifier`, sends only its hash on the way out, and presents the
+ * original when exchanging the code. An attacker who intercepts the code has neither.
+ *
+ * `state` is the other half, and a different problem: it proves the callback belongs to
+ * a flow this client started, which is what stops a forged callback.
+ *
+ * Everything here goes through the Web Crypto API, which every browser with custom
+ * elements has, and which Node has had since 18.
+ */
+/** URL-safe base64 with the padding removed, as the spec requires. */
+function base64url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Cryptographically random, never `Math.random`. */
+function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    return bytes;
+}
+/** A `code_verifier`: 43 to 128 characters from the unreserved set. */
+export function createVerifier() {
+    return base64url(randomBytes(32));
+}
+/** A `state` or `nonce`. Same shape, different job. */
+export function createStateValue() {
+    return base64url(randomBytes(16));
+}
+/**
+ * The `code_challenge` for a verifier, as S256.
+ *
+ * The `plain` method is in the spec and is worth nothing: it sends the verifier itself.
+ * This package does not offer it.
+ */
+export async function createChallenge(verifier) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64url(new Uint8Array(digest));
+}
+/** A verifier with its challenge, which is how a caller always wants them. */
+export async function createPkcePair() {
+    const verifier = createVerifier();
+    return { verifier, challenge: await createChallenge(verifier) };
+}
+/**
+ * Compare two `state` values without leaking where they differ.
+ *
+ * The timing of a `===` on strings depends on the first differing character. That is a
+ * weak signal here, since state is single-use and short-lived, but comparing it properly
+ * costs nothing.
+ */
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** Epoch milliseconds from an `expires_in` in seconds. */
+export function expiryFrom(expiresIn, now = Date.now()) {
+    const seconds = typeof expiresIn === 'number' ? expiresIn : Number(expiresIn);
+    return Number.isFinite(seconds) && seconds > 0 ? now + seconds * 1000 : undefined;
+}
+/**
+ * A JWT's payload, without verifying the signature.
+ *
+ * Legitimate for a token this client fetched itself: the code exchange is a direct TLS
+ * call to the token endpoint, so the response is authentic by transport, which is what
+ * OIDC allows a confidential exchange to rely on. Never use this on a token that arrived
+ * from somewhere else.
+ */
+export function claimsOf(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const payload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        return JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, '=')));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `exp` of a JWT, in epoch milliseconds.
+ *
+ * Reads the payload without verifying the signature, which is correct for this use: the
+ * client is deciding when to refresh, not whether to trust the token. The server that
+ * receives it verifies it properly.
+ */
+export function expiryFromJwt(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const payload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const json = JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, '=')));
+        return typeof json.exp === 'number' ? json.exp * 1000 : null;
+    }
+    catch {
+        // An opaque access token is not a JWT and has no `exp` to read. The caller falls
+        // back to `expires_in`.
+        return null;
+    }
+}

package/dist/pkce.mjs

@@ -0,0 +1,66 @@
+// src/pkce.ts
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomBytes(length) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+function createVerifier() {
+  return base64url(randomBytes(32));
+}
+function createStateValue() {
+  return base64url(randomBytes(16));
+}
+async function createChallenge(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+async function createPkcePair() {
+  const verifier = createVerifier();
+  return { verifier, challenge: await createChallenge(verifier) };
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function expiryFrom(expiresIn, now = Date.now()) {
+  const seconds = typeof expiresIn === "number" ? expiresIn : Number(expiresIn);
+  return Number.isFinite(seconds) && seconds > 0 ? now + seconds * 1e3 : void 0;
+}
+function claimsOf(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    return JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, "=")));
+  } catch {
+    return null;
+  }
+}
+function expiryFromJwt(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const json = JSON.parse(atob(payload.padEnd(Math.ceil(payload.length / 4) * 4, "=")));
+    return typeof json.exp === "number" ? json.exp * 1e3 : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  claimsOf,
+  createChallenge,
+  createPkcePair,
+  createStateValue,
+  createVerifier,
+  expiryFrom,
+  expiryFromJwt,
+  timingSafeEqual
+};

package/dist/presets.cjs

@@ -0,0 +1,240 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/presets.ts
+var presets_exports = {};
+__export(presets_exports, {
+  presets: () => presets
+});
+module.exports = __toCommonJS(presets_exports);
+
+// src/roles.ts
+var rolesFrom = {
+  /** Keycloak, realm roles. Where it puts them unless a client mapper is configured. */
+  keycloakRealm: (claims) => {
+    const realm = claims.realm_access;
+    return realm?.roles ?? [];
+  },
+  /** Keycloak, roles scoped to one client rather than the realm. */
+  keycloakClient: (clientId) => (claims) => {
+    const all = claims.resource_access;
+    return all?.[clientId]?.roles ?? [];
+  },
+  /** Okta, and anything else using a groups claim. Needs a groups claim on the token. */
+  groups: (claims) => Array.isArray(claims.groups) ? claims.groups : [],
+  /** Cognito, which namespaces the claim. */
+  cognito: (claims) => {
+    const groups = claims["cognito:groups"];
+    return Array.isArray(groups) ? groups : [];
+  },
+  /**
+   * Auth0, which requires a namespaced custom claim added by an action.
+   *
+   * `rolesFrom.namespaced('https://adafri.com/roles')`. Auth0 silently drops a custom claim
+   * that is not a URI, so an empty list here usually means the namespace, not the action.
+   */
+  namespaced: (claim) => (claims) => {
+    const value = claims[claim];
+    return Array.isArray(value) ? value : [];
+  },
+  /** The `scope` claim read as a role list, for a provider issuing no roles at all. */
+  scope: (claims) => typeof claims.scope === "string" ? claims.scope.split(" ") : []
+};
+
+// src/presets.ts
+var trim = (url) => url.replace(/\/+$/, "");
+var presets = {
+  /**
+   * Any OIDC provider publishing a discovery document.
+   *
+   * The agnostic path, and the one to reach for first. A provider not listed below almost
+   * certainly works through this.
+   */
+  oidc(options) {
+    return {
+      label: options.issuer,
+      client: { issuer: trim(options.issuer), scopes: options.scopes },
+      roles: options.roles ?? rolesFrom.scope,
+      verifier: (clientId) => ({
+        issuer: trim(options.issuer),
+        audience: options.audience ?? clientId,
+        ...options.audience === false ? { authorizedParty: clientId } : {}
+      }),
+      constraints: []
+    };
+  },
+  /**
+   * A plain OAuth2 server with no discovery document.
+   *
+   * Every endpoint is given, because there is nothing to ask. Token verification needs an
+   * issuer regardless, since a verifier will not accept a token without one.
+   */
+  oauth2(options) {
+    return {
+      label: options.issuer,
+      client: { endpoints: options.endpoints, scopes: options.scopes },
+      roles: options.roles ?? rolesFrom.scope,
+      verifier: (clientId) => ({
+        issuer: trim(options.issuer),
+        audience: options.audience ?? clientId,
+        ...options.audience === false ? { authorizedParty: clientId } : {}
+      }),
+      constraints: ["Publishes no discovery document, so every endpoint is configured by hand."]
+    };
+  },
+  /** Keycloak. A realm is its own issuer. */
+  keycloak(options) {
+    const issuer = `${trim(options.baseUrl)}/realms/${options.realm}`;
+    return {
+      label: "Keycloak",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email"]
+      },
+      roles: rolesFrom.keycloakRealm,
+      // No `aud` on an access token until an audience mapper is configured, and the client is
+      // named in `azp` instead. So the check moves to `authorizedParty` rather than being
+      // dropped: `audience: false` alone would accept a token minted for any client of the
+      // realm, which is the check being skipped.
+      verifier: (clientId) => ({ issuer, audience: false, authorizedParty: clientId }),
+      constraints: [
+        "Puts no `aud` on an access token until a dedicated audience mapper is configured. Configure one and switch the verifier to `audience: clientId`.",
+        "Revokes the whole session when an authorization code is replayed, so a replay test has to run last."
+      ]
+    };
+  },
+  /**
+   * Auth0.
+   *
+   * `audience` is the field that decides what kind of token comes back. Without it Auth0
+   * issues an opaque token for its own userinfo endpoint and the JWT checks have nothing to
+   * work with.
+   */
+  auth0(options) {
+    const issuer = `https://${options.domain.replace(/^https?:\/\//, "").replace(/\/+$/, "")}/`;
+    return {
+      label: "Auth0",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"],
+        ...options.audience ? { extraParams: { audience: options.audience } } : {}
+      },
+      roles: options.rolesClaim ? rolesFrom.namespaced(options.rolesClaim) : rolesFrom.scope,
+      verifier: (clientId) => ({
+        issuer,
+        // The API identifier is the audience of an access token. Without one the token is
+        // opaque and there is nothing for a verifier to check.
+        audience: options.audience ?? false,
+        ...options.audience ? {} : { authorizedParty: clientId }
+      }),
+      constraints: [
+        "Issues an opaque access token unless `audience` names an API, so token verification needs it.",
+        "A refresh token needs three things together: `offline_access` in the scopes, an audience whose API has Allow Offline Access on, and Refresh Token Rotation enabled on the application. Any one missing and the scope is ignored silently.",
+        "Has no roles claim of its own. An action must add a namespaced one, and Auth0 drops a custom claim that is not a URI.",
+        "The issuer carries a trailing slash. A verifier pinned without it rejects every token."
+      ]
+    };
+  },
+  /**
+   * Okta.
+   *
+   * Two authorization servers that are not interchangeable: a custom one per application,
+   * and the org itself for Okta's own management API.
+   */
+  okta(options) {
+    const host = `https://${options.domain.replace(/^https?:\/\//, "").replace(/\/+$/, "")}`;
+    const server = options.authorizationServer === void 0 ? "default" : options.authorizationServer;
+    const issuer = server === null ? host : `${host}/oauth2/${server}`;
+    return {
+      label: "Okta",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"],
+        dpop: options.dpop ?? true
+      },
+      roles: rolesFrom.groups,
+      verifier: (clientId) => ({
+        issuer,
+        // An access token from a custom server is minted for that server's audience, named in
+        // the console and `api://default` by default. It does not carry the client id.
+        audience: false,
+        authorizedParty: clientId
+      }),
+      constraints: [
+        "Two authorization servers: /oauth2/<name> for an application, the bare domain for the management API. They are not interchangeable.",
+        "Turns DPoP on by default for a new application, and an integrator org will not let you untick it.",
+        "Binds the refresh token to the DPoP key as well as the access token, so a refresh must be proved with the key that obtained it.",
+        "A public SPA cannot introspect at all. An API Services client with `private_key_jwt` has to ask instead.",
+        "Client credentials against the org server must use `private_key_jwt`, whatever the application is set to."
+      ]
+    };
+  },
+  /**
+   * Google.
+   *
+   * Refuses a public client outright, so server mode is the only option: the token endpoint
+   * checks for a client secret before it looks at PKCE.
+   */
+  google(options = {}) {
+    return {
+      label: "Google",
+      client: {
+        issuer: "https://accounts.google.com",
+        scopes: options.scopes ?? ["openid", "profile", "email"],
+        ...options.hostedDomain ? { extraParams: { hd: options.hostedDomain } } : {}
+      },
+      roles: rolesFrom.scope,
+      verifier: (clientId) => ({
+        // Names itself two ways, and a service pinned to one rejects tokens carrying the
+        // other. Discovery uses the first.
+        issuer: ["https://accounts.google.com", "accounts.google.com"],
+        audience: clientId
+      }),
+      constraints: [
+        "Refuses a public client: the token endpoint reports `client_secret is missing` before checking PKCE, so browser mode cannot work.",
+        "Publishes its issuer both with and without a scheme, so a verifier needs both spellings.",
+        "Issues a refresh token only on the first consent unless `prompt=consent` and `access_type=offline` are sent."
+      ]
+    };
+  },
+  /**
+   * Dex.
+   *
+   * Sends no CORS headers, on discovery or the token endpoint, so a browser cannot talk to it
+   * at all. Server mode only, and giving endpoints explicitly does not help: the token request
+   * is blocked too.
+   */
+  dex(options) {
+    const issuer = trim(options.baseUrl);
+    return {
+      label: "Dex",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"]
+      },
+      roles: rolesFrom.groups,
+      verifier: (clientId) => ({ issuer, audience: clientId }),
+      constraints: [
+        "Sends no CORS headers on discovery or the token endpoint, so browser mode cannot work. Naming the endpoints explicitly only moves the failure to the token request.",
+        "Has no admin interface. Users are static entries in its config file, and a password is a bcrypt hash.",
+        "Publishes no revocation endpoint."
+      ]
+    };
+  }
+};