import axios from "axios";
import { StrKey } from "npci-payment-xdr-base";
import URI from "urijs";
import { Config } from "./config";
import { BadResponseError } from "./errors";
import { StellarTomlResolver } from "./stellar_toml_resolver";
// FEDERATION_RESPONSE_MAX_SIZE is the maximum size of response from a federation server
export const FEDERATION_RESPONSE_MAX_SIZE = 100 * 1024;
/**
* FederationServer handles a network connection to a
* [federation server](https://www.stellar.org/developers/guides/concepts/federation.html)
* instance and exposes an interface for requests to that instance.
* @constructor
* @param {string} serverURL The federation server URL (ex. `https://acme.com/federation`).
* @param {string} domain Domain this server represents
* @param {object} [opts] options object
* @param {boolean} [opts.allowHttp] - Allow connecting to http servers, default: `false`. This must be set to false in production deployments! You can also use {@link Config} class to set this globally.
* @param {number} [opts.timeout] - Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue. You can also use {@link Config} class to set this globally.
* @returns {void}
*/
export class FederationServer {
/**
* The federation server URL (ex. `https://acme.com/federation`).
*
* @memberof FederationServer
*/
private readonly serverURL: uri.URI; // TODO: public or private? readonly?
/**
* Domain this server represents.
*
* @type {string}
* @memberof FederationServer
*/
private readonly domain: string; // TODO: public or private? readonly?
/**
* Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue.
*
* @type {number}
* @memberof FederationServer
*/
private readonly timeout: number; // TODO: public or private? readonly?
/**
* A helper method for handling user inputs that contain `destination` value.
* It accepts two types of values:
*
* * For Stellar address (ex. `bob*stellar.org`) it splits Stellar address and then tries to find information about
* federation server in `stellar.toml` file for a given domain. It returns a `Promise` which resolves if federation
* server exists and user has been found and rejects in all other cases.
* * For Account ID (ex. `GB5XVAABEQMY63WTHDQ5RXADGYF345VWMNPTN2GFUDZT57D57ZQTJ7PS`) it returns a `Promise` which
* resolves if Account ID is valid and rejects in all other cases. Please note that this method does not check
* if the account actually exists in a ledger.
*
* Example:
* ```js
* StellarSdk.FederationServer.resolve('bob*stellar.org')
* .then(federationRecord => {
* // {
* // account_id: 'GB5XVAABEQMY63WTHDQ5RXADGYF345VWMNPTN2GFUDZT57D57ZQTJ7PS',
* // memo_type: 'id',
* // memo: 100
* // }
* });
* ```
*
* @see Federation doc
* @see Stellar.toml doc
* @param {string} value Stellar Address (ex. `bob*stellar.org`)
* @param {object} [opts] Options object
* @param {boolean} [opts.allowHttp] - Allow connecting to http servers, default: `false`. This must be set to false in production deployments!
* @param {number} [opts.timeout] - Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue.
* @returns {Promise} `Promise` that resolves to a JSON object with this shape:
* * `account_id` - Account ID of the destination,
* * `memo_type` (optional) - Memo type that needs to be attached to a transaction,
* * `memo` (optional) - Memo value that needs to be attached to a transaction.
*/
public static async resolve(
value: string,
opts: FederationServer.Options = {},
): Promise {
// Check if `value` is in account ID format
if (value.indexOf("*") < 0) {
if (!StrKey.isValidEd25519PublicKey(value)) {
return Promise.reject(new Error("Invalid Account ID"));
}
return Promise.resolve({ account_id: value });
}
const addressParts = value.split("*");
const [, domain] = addressParts;
if (addressParts.length !== 2 || !domain) {
return Promise.reject(new Error("Invalid Stellar address"));
}
const federationServer = await FederationServer.createForDomain(
domain,
opts,
);
return federationServer.resolveAddress(value);
}
/**
* Creates a `FederationServer` instance based on information from
* [stellar.toml](https://www.stellar.org/developers/guides/concepts/stellar-toml.html)
* file for a given domain.
*
* If `stellar.toml` file does not exist for a given domain or it does not
* contain information about a federation server Promise will reject.
* ```js
* StellarSdk.FederationServer.createForDomain('acme.com')
* .then(federationServer => {
* // federationServer.resolveAddress('bob').then(...)
* })
* .catch(error => {
* // stellar.toml does not exist or it does not contain information about federation server.
* });
* ```
* @see Stellar.toml doc
* @param {string} domain Domain to get federation server for
* @param {object} [opts] Options object
* @param {boolean} [opts.allowHttp] - Allow connecting to http servers, default: `false`. This must be set to false in production deployments!
* @param {number} [opts.timeout] - Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue.
* @returns {Promise} `Promise` that resolves to a FederationServer object
*/
public static async createForDomain(
domain: string,
opts: FederationServer.Options = {},
): Promise {
const tomlObject = await StellarTomlResolver.resolve(domain, opts);
if (!tomlObject.FEDERATION_SERVER) {
return Promise.reject(
new Error("stellar.toml does not contain FEDERATION_SERVER field"),
);
}
return new FederationServer(tomlObject.FEDERATION_SERVER, domain, opts);
}
public constructor(
serverURL: string,
domain: string,
opts: FederationServer.Options = {},
) {
// TODO `domain` regexp
this.serverURL = URI(serverURL);
this.domain = domain;
const allowHttp =
typeof opts.allowHttp === "undefined"
? Config.isAllowHttp()
: opts.allowHttp;
this.timeout =
typeof opts.timeout === "undefined" ? Config.getTimeout() : opts.timeout;
if (this.serverURL.protocol() !== "https" && !allowHttp) {
throw new Error("Cannot connect to insecure federation server");
}
}
/**
* Get the federation record if the user was found for a given Stellar address
* @see Federation doc
* @param {string} address Stellar address (ex. `bob*stellar.org`). If `FederationServer` was instantiated with `domain` param only username (ex. `bob`) can be passed.
* @returns {Promise} Promise that resolves to the federation record
*/
public async resolveAddress(
address: string,
): Promise {
let stellarAddress = address;
if (address.indexOf("*") < 0) {
if (!this.domain) {
return Promise.reject(
new Error(
"Unknown domain. Make sure `address` contains a domain (ex. `bob*stellar.org`) or pass `domain` parameter when instantiating the server object.",
),
);
}
stellarAddress = `${address}*${this.domain}`;
}
const url = this.serverURL.query({ type: "name", q: stellarAddress });
return this._sendRequest(url);
}
/**
* Given an account ID, get their federation record if the user was found
* @see Federation doc
* @param {string} accountId Account ID (ex. `GBYNR2QJXLBCBTRN44MRORCMI4YO7FZPFBCNOKTOBCAAFC7KC3LNPRYS`)
* @returns {Promise} A promise that resolves to the federation record
*/
public async resolveAccountId(
accountId: string,
): Promise {
const url = this.serverURL.query({ type: "id", q: accountId });
return this._sendRequest(url);
}
/**
* Given a transactionId, get the federation record if the sender of the transaction was found
* @see Federation doc
* @param {string} transactionId Transaction ID (ex. `3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889`)
* @returns {Promise} A promise that resolves to the federation record
*/
public async resolveTransactionId(
transactionId: string,
): Promise {
const url = this.serverURL.query({ type: "txid", q: transactionId });
return this._sendRequest(url);
}
private async _sendRequest(url: uri.URI) {
const timeout = this.timeout;
return axios
.get(url.toString(), {
maxContentLength: FEDERATION_RESPONSE_MAX_SIZE,
timeout,
})
.then((response) => {
if (
typeof response.data.memo !== "undefined" &&
typeof response.data.memo !== "string"
) {
throw new Error("memo value should be of type string");
}
return response.data;
})
.catch((response) => {
if (response instanceof Error) {
if (response.message.match(/^maxContentLength size/)) {
throw new Error(
`federation response exceeds allowed size of ${FEDERATION_RESPONSE_MAX_SIZE}`,
);
} else {
return Promise.reject(response);
}
} else {
return Promise.reject(
new BadResponseError(
`Server query failed. Server responded: ${response.status} ${response.statusText}`,
response.data,
),
);
}
});
}
}
/* tslint:disable-next-line:no-namespace */
export namespace FederationServer {
export interface Record {
account_id: string;
memo_type?: string;
memo?: string;
}
export interface Options {
allowHttp?: boolean;
timeout?: number;
}
}