requestshield 0.1.6 → 0.1.8

package/src/config.mjs

@@ -7,7 +7,7 @@ import { CliError } from "./errors.mjs";
 
 /** @typedef {'qat' | 'stg' | 'prod'} Profile */
 const PROFILES = new Set(["qat", "stg", "prod"]);
-const CONFIG_KEYS = new Set(["API_URL", "OAUTH_ISSUER", "OAUTH_CLIENT_ID", "OAUTH_AUTHORIZATION_ISSUER"]);
+const CONFIG_KEYS = new Set(["API_URL", "DOCS_URL", "OAUTH_ISSUER", "OAUTH_CLIENT_ID", "OAUTH_AUTHORIZATION_ISSUER"]);
 
 export const DEFAULT_MAVEN_REPOSITORY =
     "https://sdk.intellifend.com/packages/maven";
@@ -73,6 +73,32 @@ export function getApiUrl(profile = "prod") {
   return configuredApiUrl(readProfileConfig(profile), profile);
 }
 
+/** Public documentation selection is independent of API and OAuth settings.
+ * @param {Profile} [profile]
+ */
+export function getDocsUrl(profile = "prod") {
+  let values;
+  try { values = readProfileConfig(profile); }
+  catch (error) {
+    throw new CliError(error instanceof CliError ? error.message : "Cannot read the RequestShield documentation configuration", {code: "CONTRACT_CONFIG_INVALID", exitCode: 2});
+  }
+  if (!values.DOCS_URL) {
+    throw new CliError(`Documentation is not configured for ${getCommandName(profile)}. Set DOCS_URL in config/.env.${profile}.`, {code: "CONTRACT_CONFIG_INVALID", exitCode: 2});
+  }
+  return validateDocsUrl(values.DOCS_URL);
+}
+
+/** @param {unknown} value */
+export function validateDocsUrl(value) {
+  try {
+    if (typeof value !== "string" || !/^[\x21-\x7e]+$/.test(value) || /[\\?#]/.test(value)) throw new Error();
+    return validatedUrl(value, "DOCS_URL").replace(/\/+$/, "");
+  }
+  catch {
+    throw new CliError("DOCS_URL must be a valid HTTPS URL without credentials, query or fragment (HTTP is allowed only on loopback)", {code: "CONTRACT_CONFIG_INVALID", exitCode: 2});
+  }
+}
+
 /** @param {Record<string, string | undefined>} values @param {Profile} profile */
 function configuredApiUrl(values, profile) {
   if (!values.API_URL) {
@@ -112,7 +138,7 @@ function readProfileConfig(profile) {
     throw invalidConfig(`Cannot read config/.env.${profile} for ${getCommandName(profile)}. Restore the package configuration file.`);
   }
   if (Object.keys(values).some(key => !CONFIG_KEYS.has(key))) {
-    throw invalidConfig(`config/.env.${profile} accepts only API_URL, OAUTH_ISSUER, OAUTH_CLIENT_ID and OAUTH_AUTHORIZATION_ISSUER; do not store credentials in this file.`);
+    throw invalidConfig(`config/.env.${profile} accepts only API_URL, DOCS_URL, OAUTH_ISSUER, OAUTH_CLIENT_ID and OAUTH_AUTHORIZATION_ISSUER; do not store credentials in this file.`);
   }
   return values;
 }
@@ -120,7 +146,7 @@ function readProfileConfig(profile) {
 /** @param {unknown} value @returns {string} */
 export function validateBearerToken(value) {
   if (typeof value !== "string" || value.length > 16_384 || !/^[A-Za-z0-9._~+/-]+=*$/.test(value)) {
-    throw new CliError("The access token is invalid; run `requestshield signin` again", {
+    throw new CliError("The access token is invalid; run `requestshield login` again", {
       code: "INVALID_ACCESS_TOKEN", exitCode: 3,
     });
   }

package/src/entrypoint.mjs

@@ -3,22 +3,29 @@ import { run } from "./cli.mjs";
 import { CliError } from "./errors.mjs";
 import { getCommandInvocation, getCommandName } from "./config.mjs";
 
-/** @param {import('./config.mjs').Profile} profile */
-export async function main(profile) {
-  const command = getCommandName(profile);
-  const invocation = getCommandInvocation(profile);
+/** Render exactly one result document on JSON failures. Unknown failures are redacted.
+ * @param {string[]} argv @param {Parameters<typeof run>[1]} [deps] */
+export async function execute(argv, deps = {}) {
+  const profile = deps.profile ?? "prod";
   try {
-    await run(process.argv.slice(2), {profile});
+    await run(argv, deps);
+    return 0;
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    // Rewrite only fixed CLI guidance on stderr. Successful JSON and app names
-    // pass through untouched, including names containing "requestshield".
-    const guidance = message
-      .replaceAll("`requestshield signin`", `\`${invocation} signin\``)
-      .replaceAll("`requestshield signout`", `\`${invocation} signout\``)
+    const known = error instanceof CliError;
+    const invocation = getCommandInvocation(profile);
+    const message = (known ? error.message : "The command failed unexpectedly. Please try again.")
+      .replaceAll("`requestshield login`", `\`${invocation} login\``)
+      .replaceAll("`requestshield logout`", `\`${invocation} logout\``)
       .replaceAll("Usage: requestshield ", `Usage: ${invocation} `)
       .replace(/^  requestshield /gm, `  ${invocation} `);
-    console.error(`${command}: ${guidance}`);
-    process.exitCode = error instanceof CliError ? error.exitCode : 1;
+    const code = known ? error.code : "CLI_ERROR";
+    if (argv.includes("--json")) (deps.log ?? console.log)(JSON.stringify({error: {code, message}}, null, 2));
+    else (deps.warn ?? console.error)(`${getCommandName(profile)}: ${message}\nCode: ${code}`);
+    return known ? error.exitCode : 1;
   }
 }
+
+/** @param {import('./config.mjs').Profile} profile */
+export async function main(profile) {
+  process.exitCode = await execute(process.argv.slice(2), {profile});
+}

package/src/integration-contract-client.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+import { validateDocsUrl } from "./config.mjs";
+import { validateIntegrationContract } from "./integration-contract.mjs";
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+/** Fetch only public metadata. Never attach OAuth credentials or use Management APIs. */
+export class IntegrationContractClient {
+  /** @param {{docsUrl: string, environment: import('./config.mjs').Profile, fetchImpl?: typeof fetch, timeoutMs?: number}} options */
+  constructor({docsUrl, environment, fetchImpl = fetch, timeoutMs = 15_000}) {
+    this.url = `${validateDocsUrl(docsUrl)}/integration-contract.json`;
+    this.environment = environment;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async getContract() {
+    const controller = new AbortController();
+    /** @type {ReadableStreamDefaultReader<Uint8Array> | undefined} */
+    let reader;
+    let expired = false;
+    /** @type {NodeJS.Timeout | undefined} */
+    let timer;
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        expired = true;
+        controller.abort();
+        reject(timeout());
+      }, this.timeoutMs);
+    });
+    try {
+      const operation = (async () => {
+        const response = await this.fetchImpl(this.url, {
+          method: "GET", headers: {Accept: "application/json"},
+          credentials: "omit", redirect: "error", cache: "no-store", signal: controller.signal,
+        });
+        if (expired) { void response.body?.cancel().catch(() => {}); throw timeout(); }
+        if (!response.ok) {
+          void response.body?.cancel().catch(() => {});
+          throw new CliError(response.status === 404 ? "The public integration contract has not been published for this environment (HTTP 404)." : `The public integration contract request failed: HTTP ${response.status}.`, {code: response.status === 404 ? "CONTRACT_NOT_PUBLISHED" : "CONTRACT_FETCH_FAILED", exitCode: 1, httpStatus: response.status});
+        }
+        const mediaType = response.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase();
+        if (!mediaType || !/^application\/(?:json|[a-z0-9!#$&^_.+-]+\+json)$/.test(mediaType)
+          || Number(response.headers.get("content-length")) > MAX_BODY_BYTES) {
+          void response.body?.cancel().catch(() => {});
+          throw invalidResponse();
+        }
+        const chunks = [];
+        let size = 0;
+        if (response.body) {
+          reader = response.body.getReader();
+          while (true) {
+            const {done, value} = await reader.read();
+            if (expired) throw timeout();
+            if (done) break;
+            size += value.byteLength;
+            if (size > MAX_BODY_BYTES) throw invalidResponse();
+            chunks.push(value);
+          }
+        }
+        try {
+          const body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(Buffer.concat(chunks)));
+          return validateIntegrationContract(body, this.environment);
+        } catch { throw invalidResponse(); }
+      })();
+      return await Promise.race([operation, /** @type {Promise<never>} */ (deadline)]);
+    } catch (error) {
+      if (expired) throw timeout();
+      if (error instanceof CliError) throw error;
+      throw new CliError("Could not retrieve the public integration contract. Check connectivity and try again.", {code: "CONTRACT_FETCH_FAILED", exitCode: 1});
+    } finally {
+      clearTimeout(timer);
+      if (reader) void reader.cancel().catch(() => {});
+      controller.abort();
+    }
+  }
+}
+
+function timeout() { return new CliError("The public integration contract request timed out. Check connectivity and try again.", {code: "CONTRACT_FETCH_FAILED", exitCode: 1}); }
+function invalidResponse() { return new CliError("The public integration contract is invalid, oversized or does not match this environment.", {code: "CONTRACT_INVALID", exitCode: 1}); }

package/src/integration-contract.mjs

@@ -0,0 +1,104 @@
+// @ts-check
+
+/** @typedef {{groupId: string, artifactId: string}} MavenArtifact */
+/** @typedef {{
+ * schemaVersion: 1, contractVersion: string, environment: 'qat' | 'stg' | 'prod',
+ * services: {challengeUrl: string},
+ * browser: {sdkVersion: string, scriptUrl: string, integrity: string,
+ * tokenHeader: 'X-IntelliFend-Token', availableModes: Array<'manual' | 'seamless'>,
+ * cspAdditions: {scriptSrc: string[], connectSrc: string[], workerSrc: string[]}},
+ * backend: {sdkVersion: string, minJdk: number, mavenRepository: string,
+ * core: MavenArtifact, springBoot3: MavenArtifact & {framework: 'Spring Boot 3 MVC'}},
+ * documentation: {browserSdk: string, javaSdk: string, domainsAndCsp: string}
+ * }} IntegrationContract */
+
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const ENVIRONMENTS = new Set(['qat', 'stg', 'prod']);
+
+/** Shared by the CLI reader and customer-docs build checks. This module performs
+ * no I/O and includes no release data; customer-docs owns the selected releases.
+ * Schema 1 rejects extra fields so unreviewed content never reaches CLI output.
+ * @param {unknown} value
+ * @param {string} expectedEnvironment
+ * @returns {{data: IntegrationContract}}
+ */
+export function validateIntegrationContract(value, expectedEnvironment) {
+  const envelope = object(value, ['data']);
+  const data = object(envelope.data, ['schemaVersion', 'contractVersion', 'environment', 'services', 'browser', 'backend', 'documentation']);
+  check(data.schemaVersion === 1 && ENVIRONMENTS.has(expectedEnvironment) && data.environment === expectedEnvironment);
+  version(data.contractVersion);
+
+  const services = object(data.services, ['challengeUrl']);
+  const challenge = publicUrl(services.challengeUrl);
+  const browser = object(data.browser, ['sdkVersion', 'scriptUrl', 'integrity', 'tokenHeader', 'availableModes', 'cspAdditions']);
+  version(browser.sdkVersion);
+  const script = publicUrl(browser.scriptUrl);
+  check(script.pathname.endsWith(`/requestshield/v${browser.sdkVersion}/intellifend.js`));
+  check(typeof browser.integrity === 'string' && /^sha384-[A-Za-z0-9+/]{64}$/.test(browser.integrity));
+  check(browser.tokenHeader === 'X-IntelliFend-Token');
+  const modes = stringList(browser.availableModes, 2);
+  check(modes.includes('manual') && modes.every(mode => mode === 'manual' || mode === 'seamless'));
+
+  const csp = object(browser.cspAdditions, ['scriptSrc', 'connectSrc', 'workerSrc']);
+  const scriptSources = origins(csp.scriptSrc);
+  const connectSources = origins(csp.connectSrc);
+  check(scriptSources.includes(script.origin) && connectSources.includes(challenge.origin));
+  const workerSources = stringList(csp.workerSrc, 1);
+  check(workerSources.length === 1 && workerSources[0] === 'blob:');
+
+  const backend = object(data.backend, ['sdkVersion', 'minJdk', 'mavenRepository', 'core', 'springBoot3']);
+  version(backend.sdkVersion);
+  check(typeof backend.minJdk === 'number' && Number.isSafeInteger(backend.minJdk) && backend.minJdk >= 17 && backend.minJdk <= 100);
+  publicUrl(backend.mavenRepository);
+  const core = object(backend.core, ['groupId', 'artifactId']);
+  const starter = object(backend.springBoot3, ['groupId', 'artifactId', 'framework']);
+  for (const artifact of [core, starter]) {
+    check(typeof artifact.groupId === 'string' && /^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+$/.test(artifact.groupId) && artifact.groupId.length <= 200);
+    check(typeof artifact.artifactId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(artifact.artifactId));
+  }
+  check(starter.framework === 'Spring Boot 3 MVC');
+  const docs = object(data.documentation, ['browserSdk', 'javaSdk', 'domainsAndCsp']);
+  for (const url of Object.values(docs)) publicUrl(url);
+  return /** @type {{data: IntegrationContract}} */ (value);
+}
+
+/** @param {unknown} condition @returns {asserts condition} */
+function check(condition) {
+  if (!condition) throw new Error('Invalid integration contract');
+}
+
+/** @param {unknown} value @param {string[]} keys @returns {Record<string, unknown>} */
+function object(value, keys) {
+  check(value !== null && typeof value === 'object' && !Array.isArray(value));
+  const record = /** @type {Record<string, unknown>} */ (value);
+  check(Object.keys(record).length === keys.length && keys.every(key => Object.hasOwn(record, key)));
+  return record;
+}
+
+/** @param {unknown} value */
+function version(value) {
+  check(typeof value === 'string' && value.length <= 64 && VERSION.test(value));
+}
+
+/** @param {unknown} value @returns {URL} */
+function publicUrl(value) {
+  check(typeof value === 'string' && value.length <= 2048 && /^[\x21-\x7e]+$/.test(value) && !/[?#\\]/.test(value));
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Invalid integration contract'); }
+  check(url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash);
+  return url;
+}
+
+/** @param {unknown} value @param {number} maximum @returns {string[]} */
+function stringList(value, maximum) {
+  check(Array.isArray(value) && value.length >= 1 && value.length <= maximum);
+  check(value.every(item => typeof item === 'string') && new Set(value).size === value.length);
+  return /** @type {string[]} */ (value);
+}
+
+/** @param {unknown} value @returns {string[]} */
+function origins(value) {
+  const list = stringList(value, 10);
+  for (const item of list) check(publicUrl(item).origin === item);
+  return list;
+}

package/src/oauth-client.mjs

@@ -58,7 +58,7 @@ export class OAuthClient {
       return this.#credentials(body);
     } catch (error) {
       if (error instanceof CliError && ["OAUTH_INVALID_GRANT", "OAUTH_REJECTED"].includes(error.code)) throw error;
-      throw new CliError("The refresh result is uncertain; run `requestshield signin` again", {code: "OAUTH_REFRESH_UNCERTAIN", exitCode: 3});
+      throw new CliError("The refresh result is uncertain; run `requestshield login` again", {code: "OAUTH_REFRESH_UNCERTAIN", exitCode: 3});
     }
   }
 
@@ -126,7 +126,7 @@ export class OAuthClient {
         } catch { throw invalidResponse(); }
         if (!response.ok) {
           if (body.error === "invalid_grant" || ["idp_refresh_token_invalid", "idp_authorization_code_invalid", "invalid_grant"].includes(String(body.error_type))) {
-            throw new CliError("Authorization was rejected; run `requestshield signin` again", {code: "OAUTH_INVALID_GRANT", exitCode: 3});
+            throw new CliError("Authorization was rejected; run `requestshield login` again", {code: "OAUTH_INVALID_GRANT", exitCode: 3});
           }
           if (response.status >= 400 && response.status < 500) {
             throw new CliError("The identity provider rejected the request; check the OAuth configuration or sign in again", {code: "OAUTH_REJECTED", exitCode: 3});

package/src/oauth-loopback.mjs

@@ -68,7 +68,7 @@ export async function createLoopbackReceiver({state, issuer, signal}) {
     else socket.destroy();
   });
   const aborted = () => {
-    rejectResult(new CliError("Sign-in was cancelled or expired; run `requestshield signin` again", {code: "SIGNIN_CANCELLED", exitCode: 3}));
+    rejectResult(new CliError("Sign-in was cancelled or expired; run `requestshield login` again", {code: "SIGNIN_CANCELLED", exitCode: 3}));
     if (pendingResponse && !pendingResponse.writableEnded) pendingResponse.writeHead(400).end("Sign-in was not completed. Return to your terminal.");
     server.close();
     server.closeAllConnections();

package/src/session-files.mjs

@@ -79,7 +79,7 @@ export class SessionFiles {
     } catch (error) {
       if (error instanceof CliError) throw error;
       if (errorCode(error) === "ENOENT") {
-        throw new CliError("Not signed in. Run `requestshield signin` first.", { code: "NOT_SIGNED_IN", exitCode: 3 });
+        throw new CliError("Not signed in. Run `requestshield login` first.", { code: "NOT_SIGNED_IN", exitCode: 3 });
       }
       throw storageFailure();
     } finally { await handle?.close().catch(() => undefined); }
@@ -108,7 +108,7 @@ export class SessionFiles {
         return true;
       } catch (error) {
         if (removed) {
-          throw new CliError("The local session was removed, but its durability could not be confirmed. Run `requestshield signout` again to confirm removal.", {
+          throw new CliError("The local session was removed, but its durability could not be confirmed. Run `requestshield logout` again to confirm removal.", {
             code: "SESSION_COMMIT_UNCERTAIN", exitCode: 7,
           });
         }
@@ -142,7 +142,7 @@ export class SessionFiles {
       await this.syncDirectory();
     } catch (error) {
       if (replaced) {
-        throw new CliError("The session was replaced, but its durability could not be confirmed. Run `requestshield signin` again if the next command cannot load it.", {
+        throw new CliError("The session was replaced, but its durability could not be confirmed. Run `requestshield login` again if the next command cannot load it.", {
           code: "SESSION_COMMIT_UNCERTAIN", exitCode: 7,
         });
       }
@@ -209,5 +209,5 @@ function permissionFailure() {
   return new CliError("Could not protect the RequestShield session for the current operating-system user. No new credentials were written.", { code: "SESSION_PERMISSION_ERROR", exitCode: 7 });
 }
 function invalidFile() {
-  return new CliError("The saved RequestShield session is invalid. Run `requestshield signin` again.", { code: "INVALID_SESSION", exitCode: 3 });
+  return new CliError("The saved RequestShield session is invalid. Run `requestshield login` again.", { code: "INVALID_SESSION", exitCode: 3 });
 }

package/src/session-store.mjs

@@ -180,12 +180,12 @@ function checkedCredentials(value) {
 }
 
 function invalidSession() {
-  return new CliError("The saved RequestShield session is invalid or belongs to different OAuth configuration. Run `requestshield signin` again.", {
+  return new CliError("The saved RequestShield session is invalid or belongs to different OAuth configuration. Run `requestshield login` again.", {
     code: "INVALID_SESSION", exitCode: 3,
   });
 }
 function signinRequired() {
-  return new CliError("The RequestShield session could not be safely refreshed. Run `requestshield signin` again.", {
+  return new CliError("The RequestShield session could not be safely refreshed. Run `requestshield login` again.", {
     code: "SESSION_SIGNIN_REQUIRED", exitCode: 3,
   });
 }