@fluixi/oauth2 1.0.0-alpha.1

package/dist/env-credentials.cjs

@@ -0,0 +1,82 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/env-credentials.ts
+var env_credentials_exports = {};
+__export(env_credentials_exports, {
+  credentialsFromEnv: () => credentialsFromEnv,
+  explainCredentials: () => explainCredentials
+});
+module.exports = __toCommonJS(env_credentials_exports);
+async function jwkAt(path) {
+  const [{ readFileSync }, { homedir }] = await Promise.all([
+    import("node:fs"),
+    import("node:os")
+  ]);
+  const file = path.replace(/^~(?=$|\/)/, homedir());
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    throw new Error(
+      `[fluixi/oauth2] the key file ${file} cannot be read. A signing key is named by path so it can stay outside the repository.`
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`[fluixi/oauth2] ${file} is not JSON, and a private key is expected as a JWK.`);
+  }
+}
+async function credentialsFromEnv(options) {
+  const source = options.env ?? (typeof process === "undefined" ? {} : process.env);
+  const upper = options.prefix.toUpperCase();
+  const prefer = (options.preferPrefix ?? `${upper}_INTROSPECT`).toUpperCase();
+  const read = (suffix) => source[`${prefer}_${suffix}`] ?? source[`${upper}_${suffix}`];
+  const clientId = read("CLIENT_ID") ?? options.clientId;
+  if (!clientId) return null;
+  const keyPath = read("PRIVATE_KEY");
+  if (keyPath) {
+    return {
+      clientId,
+      privateKey: await jwkAt(keyPath),
+      keyId: read("KEY_ID"),
+      clientAuthMethod: "private_key_jwt",
+      assertionAlgorithm: read("ASSERTION_ALG")
+    };
+  }
+  const clientSecret = read("SECRET") ?? read("CLIENT_SECRET");
+  if (clientSecret) return { clientId, clientSecret };
+  return null;
+}
+function explainCredentials(options) {
+  const upper = options.prefix.toUpperCase();
+  const who = options.label ?? options.prefix;
+  return `This call authenticates its caller, so ${who} needs credentials. For a client with a shared secret, set ${upper}_CLIENT_SECRET. For one registered with a public key (Okta calls this "Public key / Private key"), set ${upper}_PRIVATE_KEY to the path of its private JWK and ${upper}_KEY_ID to the kid the provider lists. Prefix either with ${upper}_INTROSPECT_ to have a different client ask, which Okta requires: a public SPA cannot introspect at all.`;
+}

package/dist/env-credentials.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Working out how a client proves who it is, from the environment.
+ *
+ * Introspection and revocation authenticate their caller and the provider decides how. Two
+ * ways are in use and they are exclusive: a shared secret, or a signature from a key whose
+ * public half the provider holds. Which one applies is a choice made in the provider's
+ * console, so code that assumes a secret describes a field that, for an Okta client set to
+ * "Public key / Private key", does not exist.
+ *
+ * Server side. A signing key and a client secret are both things a page must never see, so
+ * nothing here may be reached from a browser bundle. The file read is loaded on demand so
+ * importing this module does not require node.
+ */
+import type { ClientAuthMethod } from './client-auth.js';
+/** What a client needs to authenticate itself, shaped for the options these take. */
+export interface EnvCredentials {
+    clientId: string;
+    clientSecret?: string;
+    privateKey?: Record<string, unknown>;
+    keyId?: string;
+    clientAuthMethod?: ClientAuthMethod;
+    assertionAlgorithm?: string;
+}
+export interface EnvCredentialsOptions {
+    /**
+     * Prefix for the variable names, upper-cased. `okta` reads `OKTA_CLIENT_SECRET` and the
+     * rest.
+     */
+    prefix: string;
+    /** Used when no `<PREFIX>_CLIENT_ID` is set, usually the client the app signs people in with. */
+    clientId?: string;
+    /**
+     * A second prefix tried first, for a provider that wants a different client to ask than
+     * the one that signed the user in. Okta needs this: a public SPA cannot introspect, so an
+     * API Services client does it.
+     *
+     * Defaults to `<PREFIX>_INTROSPECT`.
+     */
+    preferPrefix?: string;
+    /** Where to read variables from. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Credentials for one provider, or null when none are configured.
+ *
+ * A named key that cannot be read throws rather than returning null: that is a mistake in
+ * the configuration, not an absence of it, and the two need different answers.
+ *
+ * @example
+ * ```ts
+ * const credentials = await credentialsFromEnv({ prefix: 'okta', clientId: config.clientId });
+ * if (!credentials) return Response.json({ error: explainCredentials({ prefix: 'okta' }) }, { status: 501 });
+ *
+ * const introspect = createTokenIntrospector({ issuer, ...credentials, audience: false });
+ * ```
+ */
+export declare function credentialsFromEnv(options: EnvCredentialsOptions): Promise<EnvCredentials | null>;
+/**
+ * What to set, when nothing is.
+ *
+ * Names both ways, because a message naming only the secret sends someone hunting for a
+ * field their client does not have.
+ */
+export declare function explainCredentials(options: {
+    prefix: string;
+    label?: string;
+}): string;
+//# sourceMappingURL=env-credentials.d.ts.map

package/dist/env-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-credentials.d.ts","sourceRoot":"","sources":["../src/env-credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA2BhC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAWtF"}

package/dist/env-credentials.js

@@ -0,0 +1,76 @@
+/** Reads a JWK from a path, with `~` expanded. Node only, and only when a key is named. */
+async function jwkAt(path) {
+    const [{ readFileSync }, { homedir }] = await Promise.all([
+        import('node:fs'),
+        import('node:os'),
+    ]);
+    const file = path.replace(/^~(?=$|\/)/, homedir());
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        throw new Error(`[fluixi/oauth2] the key file ${file} cannot be read. A signing key is named by path so it can stay outside the repository.`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`[fluixi/oauth2] ${file} is not JSON, and a private key is expected as a JWK.`);
+    }
+}
+/**
+ * Credentials for one provider, or null when none are configured.
+ *
+ * A named key that cannot be read throws rather than returning null: that is a mistake in
+ * the configuration, not an absence of it, and the two need different answers.
+ *
+ * @example
+ * ```ts
+ * const credentials = await credentialsFromEnv({ prefix: 'okta', clientId: config.clientId });
+ * if (!credentials) return Response.json({ error: explainCredentials({ prefix: 'okta' }) }, { status: 501 });
+ *
+ * const introspect = createTokenIntrospector({ issuer, ...credentials, audience: false });
+ * ```
+ */
+export async function credentialsFromEnv(options) {
+    const source = options.env ?? (typeof process === 'undefined' ? {} : process.env);
+    const upper = options.prefix.toUpperCase();
+    const prefer = (options.preferPrefix ?? `${upper}_INTROSPECT`).toUpperCase();
+    const read = (suffix) => source[`${prefer}_${suffix}`] ?? source[`${upper}_${suffix}`];
+    const clientId = read('CLIENT_ID') ?? options.clientId;
+    if (!clientId)
+        return null;
+    // A key wins over a secret. A client configured both ways at the provider is unusual, and
+    // the key is the stronger of the two.
+    const keyPath = read('PRIVATE_KEY');
+    if (keyPath) {
+        return {
+            clientId,
+            privateKey: await jwkAt(keyPath),
+            keyId: read('KEY_ID'),
+            clientAuthMethod: 'private_key_jwt',
+            assertionAlgorithm: read('ASSERTION_ALG'),
+        };
+    }
+    const clientSecret = read('SECRET') ?? read('CLIENT_SECRET');
+    if (clientSecret)
+        return { clientId, clientSecret };
+    return null;
+}
+/**
+ * What to set, when nothing is.
+ *
+ * Names both ways, because a message naming only the secret sends someone hunting for a
+ * field their client does not have.
+ */
+export function explainCredentials(options) {
+    const upper = options.prefix.toUpperCase();
+    const who = options.label ?? options.prefix;
+    return (`This call authenticates its caller, so ${who} needs credentials. ` +
+        `For a client with a shared secret, set ${upper}_CLIENT_SECRET. ` +
+        `For one registered with a public key (Okta calls this "Public key / Private key"), set ` +
+        `${upper}_PRIVATE_KEY to the path of its private JWK and ${upper}_KEY_ID to the kid the ` +
+        `provider lists. Prefix either with ${upper}_INTROSPECT_ to have a different client ask, ` +
+        `which Okta requires: a public SPA cannot introspect at all.`);
+}

package/dist/env-credentials.mjs

@@ -0,0 +1,51 @@
+// src/env-credentials.ts
+async function jwkAt(path) {
+  const [{ readFileSync }, { homedir }] = await Promise.all([
+    import("node:fs"),
+    import("node:os")
+  ]);
+  const file = path.replace(/^~(?=$|\/)/, homedir());
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    throw new Error(
+      `[fluixi/oauth2] the key file ${file} cannot be read. A signing key is named by path so it can stay outside the repository.`
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`[fluixi/oauth2] ${file} is not JSON, and a private key is expected as a JWK.`);
+  }
+}
+async function credentialsFromEnv(options) {
+  const source = options.env ?? (typeof process === "undefined" ? {} : process.env);
+  const upper = options.prefix.toUpperCase();
+  const prefer = (options.preferPrefix ?? `${upper}_INTROSPECT`).toUpperCase();
+  const read = (suffix) => source[`${prefer}_${suffix}`] ?? source[`${upper}_${suffix}`];
+  const clientId = read("CLIENT_ID") ?? options.clientId;
+  if (!clientId) return null;
+  const keyPath = read("PRIVATE_KEY");
+  if (keyPath) {
+    return {
+      clientId,
+      privateKey: await jwkAt(keyPath),
+      keyId: read("KEY_ID"),
+      clientAuthMethod: "private_key_jwt",
+      assertionAlgorithm: read("ASSERTION_ALG")
+    };
+  }
+  const clientSecret = read("SECRET") ?? read("CLIENT_SECRET");
+  if (clientSecret) return { clientId, clientSecret };
+  return null;
+}
+function explainCredentials(options) {
+  const upper = options.prefix.toUpperCase();
+  const who = options.label ?? options.prefix;
+  return `This call authenticates its caller, so ${who} needs credentials. For a client with a shared secret, set ${upper}_CLIENT_SECRET. For one registered with a public key (Okta calls this "Public key / Private key"), set ${upper}_PRIVATE_KEY to the path of its private JWK and ${upper}_KEY_ID to the kid the provider lists. Prefix either with ${upper}_INTROSPECT_ to have a different client ask, which Okta requires: a public SPA cannot introspect at all.`;
+}
+export {
+  credentialsFromEnv,
+  explainCredentials
+};