@fluixi/oauth2 1.0.0-alpha.1

package/dist/service-client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `client_credentials`: a token for the service itself, with no user involved.
+ *
+ * The other flows in this package answer "who is using this app". This answers "which
+ * service is calling", which is the other half of most systems: a background job reading
+ * an API, one service talking to another, a webhook handler that needs to write back.
+ *
+ * Server side only, and not negotiably so. The grant is the client secret, so anything
+ * holding it can mint tokens as this service. A browser cannot keep one.
+ *
+ * ```ts
+ * const orders = createServiceClient({
+ *   issuer: process.env.OIDC_ISSUER!,
+ *   clientId: 'reports-job',
+ *   clientSecret: process.env.REPORTS_SECRET!,
+ *   scopes: ['orders:read'],
+ * });
+ *
+ * const response = await fetch('https://api.example.com/orders', {
+ *   headers: { authorization: `Bearer ${await orders.token()}` },
+ * });
+ * ```
+ */
+import { type ClientAuthMethodInput } from './client-auth.js';
+export interface ServiceClientOptions {
+    /** The issuer, for discovery. Give `tokenEndpoint` instead to skip the request. */
+    issuer?: string;
+    tokenEndpoint?: string;
+    clientId: string;
+    /** Not needed with `private_key_jwt`. */
+    clientSecret?: string;
+    /** What the service is asking to do. Provider-specific. */
+    scopes?: string[];
+    /**
+     * Some providers want the API being called named here rather than in a scope. Auth0
+     * issues an opaque token instead of a JWT without it.
+     */
+    audience?: string;
+    /**
+     * How this service proves who it is.
+     *
+     * `basic` puts the secret in an Authorization header, `body` in the form. `private_key_jwt`
+     * sends a short-lived assertion signed with a key the provider knows the public half of,
+     * and no secret travels at all.
+     *
+     * Not merely a preference everywhere. Okta's org authorization server refuses client
+     * credentials with anything but `private_key_jwt`, and FAPI requires it.
+     */
+    clientAuthMethod?: ClientAuthMethodInput;
+    /**
+     * The signing key for `private_key_jwt`, as a JWK.
+     *
+     * The provider holds the public half. Nothing derived from it leaves this process
+     * except a signature, which is the point: there is no shared secret to leak.
+     */
+    privateKey?: Record<string, unknown>;
+    /**
+     * The `kid` to name in the assertion header.
+     *
+     * Needed when the provider holds more than one key for this client, so it knows which
+     * to verify against. Taken from the key itself when the key carries one.
+     */
+    keyId?: string;
+    /** Signing algorithm for the assertion. Default `RS256`. */
+    assertionAlgorithm?: string;
+    /** Extra parameters on the token request, for anything a provider adds. */
+    extraParams?: Record<string, string>;
+    /**
+     * Fetch a new token this many milliseconds before the current one expires.
+     *
+     * Default 30 seconds. A token that expires in flight fails a request that was fine
+     * when it started, which is the failure this exists to avoid.
+     */
+    refreshSkewMs?: number;
+}
+export interface ServiceClient {
+    /** A valid access token, from cache when one is still good. */
+    token(): Promise<string>;
+    /** Everything the token endpoint returned, for a caller that needs the scope or expiry. */
+    current(): Promise<{
+        accessToken: string;
+        expiresAt?: number;
+        scope?: string;
+    }>;
+    /** Drop the cached token, so the next call fetches a new one. */
+    reset(): void;
+}
+export declare function createServiceClient(options: ServiceClientOptions): ServiceClient;
+//# sourceMappingURL=service-client.d.ts.map

package/dist/service-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-client.d.ts","sourceRoot":"","sources":["../src/service-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,2FAA2F;IAC3F,OAAO,IAAI,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,iEAAiE;IACjE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAsGhF"}

package/dist/service-client.js

@@ -0,0 +1,112 @@
+/**
+ * `client_credentials`: a token for the service itself, with no user involved.
+ *
+ * The other flows in this package answer "who is using this app". This answers "which
+ * service is calling", which is the other half of most systems: a background job reading
+ * an API, one service talking to another, a webhook handler that needs to write back.
+ *
+ * Server side only, and not negotiably so. The grant is the client secret, so anything
+ * holding it can mint tokens as this service. A browser cannot keep one.
+ *
+ * ```ts
+ * const orders = createServiceClient({
+ *   issuer: process.env.OIDC_ISSUER!,
+ *   clientId: 'reports-job',
+ *   clientSecret: process.env.REPORTS_SECRET!,
+ *   scopes: ['orders:read'],
+ * });
+ *
+ * const response = await fetch('https://api.example.com/orders', {
+ *   headers: { authorization: `Bearer ${await orders.token()}` },
+ * });
+ * ```
+ */
+import { applyClientAuth, assertUsable, resolveMethod, } from './client-auth.js';
+import { discover } from './discovery.js';
+import { expiryFrom } from './pkce.js';
+import { OAuthError } from './types.js';
+export function createServiceClient(options) {
+    const auth = {
+        clientId: options.clientId,
+        method: options.clientAuthMethod,
+        clientSecret: options.clientSecret,
+        privateKey: options.privateKey,
+        keyId: options.keyId,
+        assertionAlgorithm: options.assertionAlgorithm,
+    };
+    // This grant *is* the credential, so a client with nothing to prove cannot use it. That
+    // also keeps it off a browser, which can hold neither a secret nor a key.
+    if (resolveMethod(auth) === 'none') {
+        throw new Error('[fluixi/oauth2] createServiceClient needs credentials: a clientSecret, or private_key_jwt with a key. This grant is the credential, so it belongs on a server and never in a browser.');
+    }
+    assertUsable(auth, 'createServiceClient');
+    if (!options.issuer && !options.tokenEndpoint) {
+        throw new Error('[fluixi/oauth2] createServiceClient needs an issuer or a tokenEndpoint.');
+    }
+    const skew = options.refreshSkewMs ?? 30_000;
+    let cached = null;
+    /**
+     * The request in flight, if any.
+     *
+     * Without it, a burst of calls on a cold cache each start their own token request, and
+     * a provider that rate-limits the token endpoint sees them all at once.
+     */
+    let pending = null;
+    let endpoint = options.tokenEndpoint ?? null;
+    async function resolveEndpoint() {
+        if (endpoint)
+            return endpoint;
+        const endpoints = await discover(options.issuer);
+        endpoint = endpoints.token;
+        return endpoint;
+    }
+    const stillGood = () => cached !== null && (cached.expiresAt === undefined || cached.expiresAt - skew > Date.now());
+    async function request() {
+        const url = await resolveEndpoint();
+        const headers = {
+            'content-type': 'application/x-www-form-urlencoded',
+            accept: 'application/json',
+        };
+        const form = new URLSearchParams({ grant_type: 'client_credentials', ...options.extraParams });
+        if (options.scopes?.length)
+            form.set('scope', options.scopes.join(' '));
+        if (options.audience)
+            form.set('audience', options.audience);
+        await applyClientAuth(auth, url, headers, form);
+        const response = await fetch(url, { method: 'POST', headers, body: form.toString() });
+        const payload = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            // The description carries the reason; the code alone rarely does. Both in the
+            // message, because a caller logging `error.message` should not have to know to
+            // reach for `error.description` as well.
+            const reason = [payload.error, payload.error_description].filter(Boolean).join(': ');
+            throw new OAuthError(`The token endpoint refused this service: ${reason || response.status}`, String(payload.error ?? 'client_credentials_failed'), typeof payload.error_description === 'string' ? payload.error_description : undefined);
+        }
+        const accessToken = String(payload.access_token ?? '');
+        if (!accessToken) {
+            throw new OAuthError('The token response carried no access_token.', 'no_access_token');
+        }
+        cached = {
+            accessToken,
+            expiresAt: expiryFrom(payload.expires_in),
+            scope: typeof payload.scope === 'string' ? payload.scope : undefined,
+        };
+        return cached;
+    }
+    async function current() {
+        if (stillGood())
+            return cached;
+        // One request per cold cache, however many callers arrive at once.
+        pending ??= request().finally(() => {
+            pending = null;
+        });
+        return pending;
+    }
+    return {
+        current,
+        token: async () => (await current()).accessToken,
+        reset: () => {
+            cached = null;
+        },
+    };
+}

package/dist/service-client.mjs

@@ -0,0 +1,213 @@
+/*! @fluixi/oauth2 v1.0.0-alpha.1 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+import "./chunk-25WE6UWI.mjs";
+
+// src/types.ts
+var OAuthError = class extends Error {
+  constructor(message, code, description) {
+    super(message);
+    this.code = code;
+    this.description = description;
+    this.name = "OAuthError";
+  }
+};
+
+// src/client-auth.ts
+var CANONICAL = {
+  basic: "client_secret_basic",
+  body: "client_secret_post",
+  client_secret_basic: "client_secret_basic",
+  client_secret_post: "client_secret_post",
+  private_key_jwt: "private_key_jwt",
+  none: "none"
+};
+function resolveMethod(auth) {
+  if (auth.method) return CANONICAL[auth.method] ?? "client_secret_basic";
+  if (auth.privateKey) return "private_key_jwt";
+  return auth.clientSecret ? "client_secret_basic" : "none";
+}
+function assertUsable(auth, who) {
+  if (!auth.clientId) throw new Error(`[fluixi/oauth2] ${who} needs a clientId.`);
+  const method = resolveMethod(auth);
+  if (method === "private_key_jwt" && !auth.privateKey) {
+    throw new Error(
+      `[fluixi/oauth2] ${who}: private_key_jwt needs \`privateKey\`, the JWK whose public half the provider holds.`
+    );
+  }
+  if ((method === "client_secret_basic" || method === "client_secret_post") && !auth.clientSecret) {
+    throw new Error(
+      `[fluixi/oauth2] ${who}: ${method} needs a \`clientSecret\`. A public client should use \`method: 'none'\`, which PKCE is what protects.`
+    );
+  }
+  return method;
+}
+async function loadJose() {
+  try {
+    return await import("./browser-ONMHX3Z3.mjs");
+  } catch {
+    throw new OAuthError(
+      "private_key_jwt needs `jose`. Install it: npm i jose. It is an optional peer, so a client using a secret does not carry it.",
+      "jose_missing"
+    );
+  }
+}
+async function signAssertion(auth, endpoint) {
+  const jose = await loadJose();
+  const alg = auth.assertionAlgorithm ?? "RS256";
+  const key = await jose.importJWK(auth.privateKey, alg);
+  const kid = auth.keyId ?? auth.privateKey.kid;
+  return new jose.SignJWT({}).setProtectedHeader(kid ? { alg, kid } : { alg }).setIssuer(auth.clientId).setSubject(auth.clientId).setAudience(endpoint).setJti(crypto.randomUUID()).setIssuedAt().setExpirationTime("1m").sign(key);
+}
+async function applyClientAuth(auth, endpoint, headers, form) {
+  switch (resolveMethod(auth)) {
+    case "client_secret_basic": {
+      const pair = `${encodeURIComponent(auth.clientId)}:${encodeURIComponent(auth.clientSecret)}`;
+      headers.authorization = `Basic ${btoa(pair)}`;
+      break;
+    }
+    case "client_secret_post":
+      form.set("client_id", auth.clientId);
+      form.set("client_secret", auth.clientSecret);
+      break;
+    case "private_key_jwt":
+      form.set("client_id", auth.clientId);
+      form.set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer");
+      form.set("client_assertion", await signAssertion(auth, endpoint));
+      break;
+    case "none":
+      form.set("client_id", auth.clientId);
+      break;
+  }
+}
+
+// src/discovery.ts
+var cache = /* @__PURE__ */ new Map();
+function documentUrl(issuer) {
+  return `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+}
+async function discover(issuer, fetcher = fetch) {
+  const cached = cache.get(issuer);
+  if (cached) return cached;
+  const pending = (async () => {
+    let response;
+    try {
+      response = await fetcher(documentUrl(issuer));
+    } catch (cause) {
+      throw new OAuthError(
+        `Could not read the discovery document at ${documentUrl(issuer)}. In a browser this is usually the provider refusing a cross-origin read: give \`endpoints\` directly, or resolve them on a server. (${cause instanceof Error ? cause.message : String(cause)})`,
+        "discovery_unreachable"
+      );
+    }
+    if (!response.ok) {
+      throw new OAuthError(
+        `Discovery failed for ${issuer}: ${response.status}`,
+        "discovery_failed"
+      );
+    }
+    const doc = await response.json();
+    if (!doc.authorization_endpoint || !doc.token_endpoint) {
+      throw new OAuthError(
+        `${issuer} published a discovery document with no authorization or token endpoint.`,
+        "discovery_incomplete"
+      );
+    }
+    return {
+      authorization: doc.authorization_endpoint,
+      token: doc.token_endpoint,
+      userinfo: doc.userinfo_endpoint,
+      endSession: doc.end_session_endpoint,
+      jwks: doc.jwks_uri,
+      introspection: doc.introspection_endpoint,
+      revocation: doc.revocation_endpoint,
+      issuer: doc.issuer ?? issuer
+    };
+  })();
+  cache.set(issuer, pending);
+  pending.catch(() => cache.delete(issuer));
+  return pending;
+}
+
+// src/pkce.ts
+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;
+}
+
+// src/service-client.ts
+function createServiceClient(options) {
+  const auth = {
+    clientId: options.clientId,
+    method: options.clientAuthMethod,
+    clientSecret: options.clientSecret,
+    privateKey: options.privateKey,
+    keyId: options.keyId,
+    assertionAlgorithm: options.assertionAlgorithm
+  };
+  if (resolveMethod(auth) === "none") {
+    throw new Error(
+      "[fluixi/oauth2] createServiceClient needs credentials: a clientSecret, or private_key_jwt with a key. This grant is the credential, so it belongs on a server and never in a browser."
+    );
+  }
+  assertUsable(auth, "createServiceClient");
+  if (!options.issuer && !options.tokenEndpoint) {
+    throw new Error("[fluixi/oauth2] createServiceClient needs an issuer or a tokenEndpoint.");
+  }
+  const skew = options.refreshSkewMs ?? 3e4;
+  let cached = null;
+  let pending = null;
+  let endpoint = options.tokenEndpoint ?? null;
+  async function resolveEndpoint() {
+    if (endpoint) return endpoint;
+    const endpoints = await discover(options.issuer);
+    endpoint = endpoints.token;
+    return endpoint;
+  }
+  const stillGood = () => cached !== null && (cached.expiresAt === void 0 || cached.expiresAt - skew > Date.now());
+  async function request() {
+    const url = await resolveEndpoint();
+    const headers = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json"
+    };
+    const form = new URLSearchParams({ grant_type: "client_credentials", ...options.extraParams });
+    if (options.scopes?.length) form.set("scope", options.scopes.join(" "));
+    if (options.audience) form.set("audience", options.audience);
+    await applyClientAuth(auth, url, headers, form);
+    const response = await fetch(url, { method: "POST", headers, body: form.toString() });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const reason = [payload.error, payload.error_description].filter(Boolean).join(": ");
+      throw new OAuthError(
+        `The token endpoint refused this service: ${reason || response.status}`,
+        String(payload.error ?? "client_credentials_failed"),
+        typeof payload.error_description === "string" ? payload.error_description : void 0
+      );
+    }
+    const accessToken = String(payload.access_token ?? "");
+    if (!accessToken) {
+      throw new OAuthError("The token response carried no access_token.", "no_access_token");
+    }
+    cached = {
+      accessToken,
+      expiresAt: expiryFrom(payload.expires_in),
+      scope: typeof payload.scope === "string" ? payload.scope : void 0
+    };
+    return cached;
+  }
+  async function current() {
+    if (stillGood()) return cached;
+    pending ??= request().finally(() => {
+      pending = null;
+    });
+    return pending;
+  }
+  return {
+    current,
+    token: async () => (await current()).accessToken,
+    reset: () => {
+      cached = null;
+    }
+  };
+}
+export {
+  createServiceClient
+};