@api-client/core 0.6.3 → 0.6.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.6.3",
+  "version": "0.6.6",
   "license": "Apache-2.0",
   "main": "build/index.js",
   "module": "build/index.js",
@@ -69,8 +69,8 @@
     "tsc:watch": "tsc --watch",
     "test:browser": "wtr --playwright --browsers chromium firefox webkit --coverage",
     "test:browser:watch": "wtr --watch --playwright --browsers chromium",
-    "test:mocha": "npm run build-ts && mocha",
-    "test": "npm run test:mocha && npm run test:browser"
+    "test:node": "npm run build-ts && mocha",
+    "test": "npm run test:node && npm run test:browser"
   },
   "husky": {
     "hooks": {

package/src/Platform.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether the current platform has the `FormData` interface
+ */
+export const hasFormData: boolean = typeof FormData === 'function';
+/**
+ * Whether the current platform has Blob interface
+ */
+export const hasBlob: boolean = typeof Blob === 'function';
+/**
+ * Whether the current platform has the `Buffer` interface.
+ */
+export const hasBuffer: boolean = typeof Buffer === 'function';

package/src/authorization/OAuth2Authorization.ts

@@ -159,7 +159,7 @@ export class OAuth2Authorization {
    * Performs the authorization.
    * @returns Promise resolved to the token info.
    */
-  authorize(): Promise<ITokenInfo> {
+  authorize(): Promise<ITokenInfo | any> {
     return new Promise((resolve, reject) => {
       this[resolveFunction] = resolve;
       this[rejectFunction] = reject;

package/src/authorization/OidcAuthorization.ts

@@ -4,6 +4,10 @@ import { OAuth2Authorization, grantResponseMapping, reportOAuthError, resolveFun
 import { nonceGenerator } from './Utils.js';
 
 export class OidcAuthorization extends OAuth2Authorization {
+  authorize(): Promise<(IOidcTokenInfo|IOidcTokenError)[]> {
+    return super.authorize();
+  }
+
   /**
    * @returns The parameters to build popup URL.
    */

package/src/authorization/Utils.ts

@@ -74,7 +74,7 @@ export function camel(name: string): string | undefined {
   while ((l = name[i])) {
     if ((l === "_" || l === "-") && i + 1 < name.length) {
       // eslint-disable-next-line no-param-reassign
-      name = name.substr(0, i) + name[i + 1].toUpperCase() + name.substr(i + 2);
+      name = name.substring(0, i) + name[i + 1].toUpperCase() + name.substring(i + 2);
       changed = true;
     }
     // eslint-disable-next-line no-plusplus

package/src/authorization/lib/SecurityProcessor.ts

@@ -0,0 +1,141 @@
+import { IBasicAuthorization, IBearerAuthorization, IOAuth2Authorization, IOidcAuthorization, IOidcTokenInfo } from "../../models/Authorization.js";
+import { IRequestAuthorization, RequestAuthorization } from "../../models/RequestAuthorization.js";
+import { IHttpRequest } from "../../models/HttpRequest.js";
+import { Headers } from '../../lib/headers/Headers.js';
+import { UrlProcessor } from "../../lib/parsers/UrlProcessor.js";
+import { UrlEncoder } from "../../lib/parsers/UrlEncoder.js";
+import { hasBuffer } from '../../Platform.js';
+import {
+  normalizeType,
+  METHOD_BASIC,
+  METHOD_BEARER,
+  METHOD_OAUTH2,
+  METHOD_OIDC,
+} from "./Utils.js";
+
+export interface IAuthApplyOptions {
+  /**
+   * When set it won't change the originating authorization objects.
+   * By default it sets the authorization's `enabled` property to `false` after applying the 
+   * value to the request.
+   */
+  immutable?: boolean;
+}
+
+export class SecurityProcessor {
+  /**
+   * Applies authorization configuration to the request object.
+   */
+  static applyAuthorization(request: IHttpRequest, authorization: (IRequestAuthorization | RequestAuthorization)[], opts: IAuthApplyOptions = {}): void {
+    if (!Array.isArray(authorization) || !authorization.length) {
+      return;
+    }
+
+    for (const auth of authorization) {
+      if (!auth.enabled || !auth.config) {
+        continue;
+      }
+
+      switch (normalizeType(auth.type)) {
+        case METHOD_BASIC:
+          SecurityProcessor.applyBasicAuth(request, auth.config as IBasicAuthorization);
+          if (!opts.immutable) {
+            auth.enabled = false;
+          }
+          break;
+        case METHOD_OAUTH2:
+          SecurityProcessor.applyOAuth2(request, auth.config as IOAuth2Authorization);
+          if (!opts.immutable) {
+            auth.enabled = false;
+          }
+          break;
+        case METHOD_OIDC:
+          SecurityProcessor.applyOpenId(request, auth.config as IOidcAuthorization);
+          if (!opts.immutable) {
+            auth.enabled = false;
+          }
+          break;
+        case METHOD_BEARER:
+          SecurityProcessor.applyBearer(request, auth.config as IBearerAuthorization);
+          if (!opts.immutable) {
+            auth.enabled = false;
+          }
+          break;
+        default:
+      }
+    }
+  }
+
+  /**
+   * Injects basic auth header into the request headers.
+   */
+  static applyBasicAuth(request: IHttpRequest, config: IBasicAuthorization): void {
+    const { username, password } = config;
+    if (!username) {
+      return;
+    }
+    const hash = `${username}:${password || ''}`;
+    const value = hasBuffer ? Buffer.from(hash).toString('base64') : btoa(hash);
+
+    const headers = new Headers(request.headers || '');
+    headers.append('authorization', `Basic ${value}`);
+    request.headers = headers.toString();
+  }
+
+  /**
+   * Injects oauth 2 auth header into the request headers.
+   */
+  static applyOAuth2(request: IHttpRequest, config: IOAuth2Authorization): void {
+    const { accessToken, tokenType = 'Bearer', deliveryMethod = 'header', deliveryName = 'authorization' } = config;
+    if (!accessToken) {
+      return;
+    }
+    const value = `${tokenType} ${accessToken}`;
+    if (deliveryMethod === 'header') {
+      const headers = new Headers(request.headers || '');
+      headers.append(deliveryName, value);
+      request.headers = headers.toString();
+    } else if (deliveryMethod === 'query') {
+      const { url } = request;
+      try {
+        const parser = new UrlProcessor(url);
+        parser.search.append(UrlEncoder.encodeQueryString(deliveryName, true), UrlEncoder.encodeQueryString(value, true));
+        request.url = parser.toString();
+      } catch (e) {
+        // ...
+      }
+    }
+  }
+
+  /**
+   * Injects OpenID Connect auth header into the request headers.
+   */
+  static applyOpenId(request: IHttpRequest, config: IOidcAuthorization): void {
+    const { accessToken, tokens, tokenInUse } = config;
+    if (accessToken) {
+      SecurityProcessor.applyOAuth2(request, config);
+    } else if (Array.isArray(tokens) && typeof tokenInUse === 'number') {
+      const data = tokens[tokenInUse] as IOidcTokenInfo;
+      if (data && data.accessToken) {
+        const copy = { ...config };
+        copy.accessToken = data.accessToken;
+        SecurityProcessor.applyOAuth2(request, copy);
+      }
+    }
+  }
+
+  /**
+   * Injects bearer auth header into the request headers.
+   */
+  static applyBearer(request: IHttpRequest, config: IBearerAuthorization): void {
+    const { token } = config;
+    if (!token) {
+      return;
+    }
+    const value = `Bearer ${token}`;
+
+    const headers = new Headers(request.headers || '');
+    headers.append('authorization', value);
+    request.headers = headers.toString();
+  }
+}

package/src/authorization/lib/Utils.ts

@@ -0,0 +1,89 @@
+/**
+ * Normalizes type name to a string identifier.
+ * It casts input to a string and lowercase it.
+ * @param type Type value
+ * @return Normalized value.
+ */
+export const normalizeType = (type?: string): string => String(type).toLowerCase();
+
+export const METHOD_BASIC = "basic";
+export const METHOD_BEARER = "bearer";
+export const METHOD_NTLM = "ntlm";
+export const METHOD_DIGEST = "digest";
+export const METHOD_OAUTH2 = "oauth 2";
+export const METHOD_OIDC = "open id";
+export const METHOD_CC = 'client certificate';
+export const CUSTOM_CREDENTIALS = "Custom credentials";
+
+/**
+ * @param value The value to validate
+ * @returns True if the redirect URI can be considered valid.
+ */
+export function validateRedirectUri(value: unknown): boolean {
+  let result = true;
+  if (!value || typeof value !== 'string') {
+    result = false;
+  }
+  // the redirect URI can have any value, especially for installed apps which 
+  // may use custom schemes. We do very basic sanity check for any script content 
+  // validation to make sure we are not passing any script.
+  if (result && String(value).startsWith('javascript:')) {
+    result = false;
+  }
+  return result;
+}
+
+/**
+ * Generates client nonce for Digest authorization.
+ *
+ * @return Generated client nonce.
+ */
+export function generateCnonce(): string {
+  const characters = 'abcdef0123456789';
+  let token = '';
+  for (let i = 0; i < 16; i++) {
+    const randNum = Math.round(Math.random() * characters.length);
+    token += characters.substring(randNum, 1);
+  }
+  return token;
+}
+
+/**
+ * Generates `state` parameter for the OAuth2 call.
+ *
+ * @return Generated state string.
+ */
+export function generateState(): string {
+  let text = '';
+  const possible = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  for (let i = 0; i < 6; i++) {
+    text += possible.charAt(Math.floor(Math.random() * possible.length));
+  }
+  return text;
+}
+
+/**
+ * When defined and the `url` is a relative path staring with `/` then it
+ * adds base URI to the path and returns concatenated value.
+ *
+ * @param url The URL to process
+ * @param baseUri Base URI to use.
+ * @returns Final URL value.
+ */
+export function readUrlValue(url?: string, baseUri?: string): string {
+  if (!url) {
+    return '';
+  }
+  const result = String(url);
+  if (!baseUri) {
+    return result;
+  }
+  if (result[0] === '/') {
+    let uri = baseUri;
+    if (uri[uri.length - 1] === '/') {
+      uri = uri.substring(0, uri.length - 1);
+    }
+    return `${uri}${result}`;
+  }
+  return result;
+}

package/src/lib/transformers/PayloadSerializer.ts

@@ -1,3 +1,5 @@
+import { hasBlob, hasBuffer, hasFormData } from '../../Platform.js';
+
 export type PayloadTypes = 'string' | 'file' | 'blob' | 'buffer' | 'arraybuffer' | 'formdata' | 'x-www-form-urlencoded';
 export type DeserializedPayload = string | Blob | File | FormData | Buffer | ArrayBuffer | undefined;
 export const SupportedPayloadTypes: PayloadTypes[] = ['string', 'file', 'blob', 'buffer', 'arraybuffer', 'formdata', 'x-www-form-urlencoded'];
@@ -17,6 +19,12 @@ export interface IMultipartBody {
    * When the previous value was a Blob or a Buffer, this will be a serialized payload.
    */
   value: string | ISafePayload;
+  /**
+   * Aside from the `value` which is used to process the Payload, the purpose of this field to to keep
+   * the entered by the user string value for the "blob" item. This is primarily handled by the UI
+   * and ignored by the HTTP Engine.
+   */
+  blobText?: string;
   /**
    * When `true` this entry represent a file part
    * @deprecated This is only used for the compatibility with ARC. This information is encoded in the `value`.
@@ -80,10 +88,6 @@ export interface ISafePayload {
  */
 export type Payload = string | ISafePayload;
 
-export const hasFormData: boolean = typeof FormData === 'function';
-export const hasBlob: boolean = typeof Blob === 'function';
-export const hasBuffer: boolean = typeof Buffer === 'function';
-
 export class PayloadSerializer {
   /**
    * Checked whether the passed payload can be safely stored in the data store.
@@ -464,6 +468,10 @@ export class PayloadSerializer {
       form.append(name, value);
       return;
     }
+    if (value.type === 'string') {
+      form.append(name, value.data as string);
+      return;
+    }
     if (value.type === 'file') {
       const file = this.deserializeFile(value);
       form.append(name, file);

package/src/models/RequestUiMeta.ts

@@ -1,5 +1,5 @@
 import { IProperty, Property } from './Property.js';
-import { IMultipartBody } from '../lib/transformers/PayloadSerializer.js';
+import { IMultipartBody, ISafePayload } from '../lib/transformers/PayloadSerializer.js';
 import { RequestUiMeta as LegacyRequestUiMeta } from './legacy/request/ArcRequest.js';
 
 export const Kind = 'Core#RequestUiMeta';
@@ -70,7 +70,7 @@ export interface IBodyMetaModel {
   /**
    * Generated view model.
    */
-  viewModel: (IProperty | IMultipartBody | IRawBody)[];
+  viewModel: (IProperty | ISafePayload | IMultipartBody | IRawBody)[];
 }
 
 /**

package/src/models/SerializablePayload.ts

@@ -1,4 +1,5 @@
-import { PayloadSerializer, Payload, DeserializedPayload, hasBuffer } from '../lib/transformers/PayloadSerializer.js';
+import { PayloadSerializer, Payload, DeserializedPayload } from '../lib/transformers/PayloadSerializer.js';
+import { hasBuffer } from '../Platform.js';
 
 export class SerializablePayload {
   /**

package/src/models/data/DataAssociation.ts

@@ -0,0 +1,189 @@
+import v4 from '../../lib/uuid.js';
+import { IThing, Thing } from "../Thing.js";
+import { IDataAssociationSchema } from './DataAssociationSchema.js';
+import { DataEntity } from './DataEntity.js';
+import { DataNamespace } from './DataNamespace.js';
+
+export const Kind = 'Core#DataAssociation';
+
+export interface IDataAssociation {
+  kind: typeof Kind;
+  /**
+   * The key of the namespace.
+   */
+  key: string;
+  /**
+   * The data association description.
+   */
+  info: IThing;
+  /**
+   * Wether the data association is required.
+   */
+  required?: boolean;
+  /**
+   * Whether the data association allows multiple items.
+   */
+  multiple?: boolean;
+  /**
+   * The target entity of this association.
+   * An association without a target is considered invalid and discarded when processing the values.
+   */
+  target?: string;
+  /**
+   * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+   */
+  schema?: IDataAssociationSchema;
+}
+
+export class DataAssociation {
+  kind = Kind;
+
+  key = '';
+
+  /**
+   * The description of the data namespace.
+   */
+  info: Thing = Thing.fromName('');
+
+  /**
+   * Wether the data association is required.
+   */
+  required?: boolean;
+
+  /**
+   * Whether the data association allows multiple items.
+   */
+  multiple?: boolean;
+
+  /**
+   * The target entity of this association.
+   * An association without a target is considered invalid and discarded when processing the values.
+   */
+  target?: string;
+
+  /**
+   * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+   * 
+   * Implementation note, when an entity is removed this property is not changed. The target can't 
+   * be read but it can be tracked to a deleted entity.
+   */
+  schema?: IDataAssociationSchema;
+
+  static fromTarget(root: DataNamespace, target: string): DataAssociation {
+    const assoc = new DataAssociation(root);
+    assoc.target = target;
+    return assoc;
+  }
+
+  static fromName(root: DataNamespace, name: string): DataAssociation {
+    const assoc = new DataAssociation(root);
+    assoc.info = Thing.fromName(name);
+    return assoc;
+  }
+
+  /**
+   * @param input The data association definition to restore.
+   */
+  constructor(protected root: DataNamespace, input?: string | IDataAssociation) {
+    let init: IDataAssociation;
+    if (typeof input === 'string') {
+      init = JSON.parse(input);
+    } else if (typeof input === 'object') {
+      init = input;
+    } else {
+      init = {
+        kind: Kind,
+        key: v4(),
+        info: Thing.fromName('').toJSON(),
+      };
+    }
+    this.new(init);
+  }
+
+  new(init: IDataAssociation): void {
+    if (!DataAssociation.isDataAssociation(init)) {
+      throw new Error(`Not a data association.`);
+    }
+    const { info, key = v4(), kind = Kind, schema, multiple, required, target } = init;
+    this.kind = kind;
+    this.key = key;
+    if (info) {
+      this.info = new Thing(info);
+    } else {
+      this.info = Thing.fromName('');
+    }
+    if (schema) {
+      this.schema = { ...schema };
+    } else {
+      this.schema = undefined;
+    }
+    if (typeof multiple === 'boolean') {
+      this.multiple = multiple;
+    } else {
+      this.multiple = undefined;
+    }
+    if (typeof required === 'boolean') {
+      this.required = required;
+    } else {
+      this.required = undefined;
+    }
+    if (typeof target === 'string') {
+      this.target = target;
+    } else {
+      this.target = undefined;
+    }
+  }
+
+  static isDataAssociation(input: unknown): boolean {
+    const typed = input as IDataAssociation;
+    if (!input || typed.kind !== Kind) {
+      return false;
+    }
+    return true;
+  }
+
+  toJSON(): IDataAssociation {
+    const result: IDataAssociation = {
+      kind: Kind,
+      key: this.key,
+      info: this.info.toJSON(),
+    };
+    if (this.schema) {
+      result.schema = { ...this.schema };
+    }
+    if (typeof this.multiple === 'boolean') {
+      result.multiple = this.multiple;
+    }
+    if (typeof this.required === 'boolean') {
+      result.required = this.required;
+    }
+    if (typeof this.target === 'string') {
+      result.target = this.target;
+    }
+    return result;
+  }
+
+  getTarget(): DataEntity | undefined {
+    const { root, target } = this;
+    if (!target) {
+      return undefined;
+    }
+    return root.definitions.entities.find(i => i.key === target);
+  }
+
+  /**
+   * Removes self from the parent entity and the namespace definition.
+   */
+  remove(): void {
+    const { root } = this;
+    const entity = root.definitions.entities.find(i => i.associations.some(j => j === this));
+    if (entity) {
+      const assocIndex = entity.associations.findIndex(i => i === this);
+      entity.associations.splice(assocIndex, 1);
+    }
+    const defIndex = this.root.definitions.associations.findIndex(i => i.key === this.key);
+    if (defIndex >= 0) {
+      this.root.definitions.associations.splice(defIndex, 1);
+    }
+  }
+}

package/src/models/data/DataAssociationSchema.ts

@@ -0,0 +1,32 @@
+export interface IDataAssociationSchema {
+  /**
+   * Whether the target entity should be embedded under the property name.
+   * When false, this association is just an information that one entity depend on another.
+   * When true, it changes the definition of the schema having this association to 
+   * add the target schema properties inline with this property.
+   * 
+   * **When true**
+   * 
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": {
+   *    "city": "example value",
+   *    ...
+   *  }
+   * }
+   * ```
+   * 
+   * **When false**
+   * 
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": "the key of the referenced schema"
+   * }
+   * ```
+   */
+  embedded?: boolean;
+}