Create a non-custodial account

import express from "express";
import type { Express, NextFunction, Request, Response } from "express";

const app: Express = express();

// Forward each allowed SDK request to Circle with your API key.
app.use(
  "/daa",
  authenticateAppSession, // Your own session check.
  express.raw({ type: () => true }), // Keep the body as raw bytes.
  async (req: Request, res: Response): Promise<void> => {
    if (DOT_SEGMENT.test(req.path) || !isAllowedRoute(req.method, req.path)) {
      res.sendStatus(404);
      return;
    }

    // Check that the request belongs to the signed-in end customer.
    const clientEntityId: string = res.locals.clientEntityId;
    const url: URL | null = await scopeToSignedInUser(req, clientEntityId);
    if (url === null) {
      res.sendStatus(404);
      return;
    }

    const headers: Record<string, string> = {
      Authorization: `Bearer ${API_KEY}`,
    };
    for (const name of FORWARDED_HEADERS) {
      const value: string | undefined = req.header(name);
      if (value !== undefined) headers[name] = value;
    }

    let upstream: globalThis.Response;
    try {
      upstream = await fetch(url, {
        method: req.method,
        headers,
        body: req.method === "GET" ? undefined : req.body,
      });
    } catch {
      res.sendStatus(502);
      return;
    }

    const body: Buffer = Buffer.from(await upstream.arrayBuffer());
    if (
      upstream.ok &&
      !(await responseBelongsTo(url.pathname, body, clientEntityId))
    ) {
      res.sendStatus(404);
      return;
    }

    res.status(upstream.status);
    upstream.headers.forEach((value: string, name: string) => {
      if (RETURNED_RESPONSE_HEADERS.includes(name)) {
        res.setHeader(name, value);
      }
    });
    res.send(body);
  },
);

app.listen(3000);

// Ownership checks. Reads and some sign-in requests don't carry the end
// customer's signature, so the relay checks them against the signed-in end
// customer. These rules cover the requests in this quickstart, and transfers and
// withdrawals. Add a rule for any other read that your application uses. The
// relay rejects every read that no rule covers.

// Returns the URL to forward, or null to reject the request.
async function scopeToSignedInUser(
  req: Request,
  clientEntityId: string,
): Promise<URL | null> {
  const url: URL = new URL(`${CIRCLE_API}${req.url}`);
  // Check the URL that the relay forwards, after parsing.
  if (url.origin !== CIRCLE_API || !isAllowedRoute(req.method, url.pathname)) {
    return null;
  }
  const path: string = url.pathname;

  if (req.method === "POST") {
    let body: {
      clientEntityId?: string;
      accountId?: string;
      custodyType?: string;
      source?: { type?: string; id?: string };
    };
    try {
      body = JSON.parse(
        Buffer.isBuffer(req.body) && req.body.length > 0
          ? req.body.toString("utf8")
          : "{}",
      );
    } catch {
      return null; // Not JSON. Circle would reject it anyway.
    }
    // Sign-in steps that aren't tied to an account.
    if (
      path === "/v1/accounts/auth/loginRequests" ||
      path === "/v1/accounts/auth/deviceKeyRegistration"
    ) {
      return url;
    }
    // Social sign-in links the user to clientEntityId permanently.
    if (path === "/v1/accounts/auth/sessions") {
      return body.clientEntityId === clientEntityId ? url : null;
    }
    // Creating a deposit address isn't signed by the end customer.
    if (path === "/v1/accounts/addresses/deposit") {
      return typeof body.accountId === "string" &&
        (await ownsAccount(body.accountId, clientEntityId))
        ? url
        : null;
    }
    // Account, transfer, and withdrawal requests. Circle checks the signature
    // only for a non-custodial account. Your API key alone can create accounts
    // and debit custodial accounts, so forward only signed requests for the
    // signed-in user's own non-custodial account.
    if (req.header("x-device-authorization") === undefined) {
      return null;
    }
    if (path === "/v1/accounts") {
      return body.custodyType === "self" &&
        body.clientEntityId === clientEntityId
        ? url
        : null;
    }
    return body.source?.type === "account" &&
      typeof body.source.id === "string" &&
      (await ownsAccount(body.source.id, clientEntityId, "self"))
      ? url
      : null;
  }

  // Lists that filter by end customer: always list the signed-in user's data.
  if (path === "/v1/accounts" || /^\/v1\/banks\/(wires|ach)$/.test(path)) {
    url.searchParams.set("clientEntityId", clientEntityId);
    return url;
  }
  // Context of the signed-in device. Signed by the end customer.
  if (path === "/v1/accounts/auth/context") {
    return url;
  }
  // A single wire or ACH bank account, or its instructions: it must be in the
  // signed-in user's list, because the response doesn't name the end customer.
  // Instructions credit the account in the accountId parameter, and Circle
  // doesn't check that it belongs to the bank account's owner, so it must be
  // one of the signed-in user's accounts too.
  const bank: RegExpMatchArray | null = path.match(
    /^\/v1\/banks\/(wires|ach)\/([^/]+)(\/instructions)?$/,
  );
  if (bank !== null) {
    const accountIds: string[] = url.searchParams.getAll("accountId");
    return (await ownsBankAccount(bank[1], bank[2], clientEntityId)) &&
      accountIds.length <= 1 &&
      (accountIds.length === 0 ||
        (await ownsAccount(accountIds[0], clientEntityId)))
      ? url
      : null;
  }
  // A single account, or its limits.
  const account: RegExpMatchArray | null = path.match(
    /^\/v1\/accounts\/([^/]+)(\/limits\/usage)?$/,
  );
  if (account !== null && !ACCOUNT_COLLECTIONS.includes(account[1])) {
    return (await ownsAccount(account[1], clientEntityId)) ? url : null;
  }
  // Lists that filter by account: require one of the user's accounts.
  if (
    /^\/v1\/accounts\/(transfers|withdrawals|deposits|transactions|addresses\/deposit)$/.test(
      path,
    )
  ) {
    // Remove filters that can widen the list beyond the account, and limit
    // the lists that accept it to the signed-in user.
    for (const name of LIST_FILTERS_TO_REMOVE) {
      url.searchParams.delete(name);
    }
    if (/^\/v1\/accounts\/(transfers|transactions)$/.test(path)) {
      url.searchParams.set("clientEntityId", clientEntityId);
    }
    const accountIds: string[] = url.searchParams.getAll("accountId");
    return accountIds.length === 1 &&
      (await ownsAccount(accountIds[0], clientEntityId))
      ? url
      : null;
  }
  // A single transfer, withdrawal, deposit, or deposit address: checked in the
  // response.
  if (SINGLE_READS.test(path)) {
    return url;
  }
  return null;
}

// Checks single reads against the account that the response names.
async function responseBelongsTo(
  path: string,
  body: Buffer,
  clientEntityId: string,
): Promise<boolean> {
  if (!SINGLE_READS.test(path)) {
    return true; // Already scoped before forwarding.
  }
  type Location = { type?: string; id?: string };
  let data: {
    source?: Location;
    destination?: Location;
    sourceAccountId?: string;
    accountId?: string;
  };
  try {
    data = JSON.parse(body.toString("utf8")).data ?? {};
  } catch {
    return false;
  }
  // The accounts that the response names. A transfer can be outgoing or
  // incoming, so either side can be the user's account.
  const accountIds: (string | undefined)[] = path.startsWith(
    "/v1/accounts/transfers/",
  )
    ? [data.source, data.destination]
        .filter((location?: Location): boolean => location?.type === "account")
        .map((location?: Location): string | undefined => location?.id)
    : path.startsWith("/v1/accounts/withdrawals/")
      ? [data.sourceAccountId]
      : path.startsWith("/v1/accounts/deposits/")
        ? [data.destination?.id]
        : [data.accountId];
  for (const accountId of accountIds) {
    if (
      accountId !== undefined &&
      (await ownsAccount(accountId, clientEntityId))
    ) {
      return true;
    }
  }
  return false;
}

async function ownsBankAccount(
  type: string,
  bankAccountId: string,
  clientEntityId: string,
): Promise<boolean> {
  const response: globalThis.Response = await fetch(
    `${CIRCLE_API}/v1/banks/${type}?clientEntityId=${encodeURIComponent(clientEntityId)}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  if (!response.ok) {
    return false;
  }
  const list: { data?: { id?: string }[] } = await response.json();
  return (list.data ?? []).some(
    (bankAccount: { id?: string }): boolean => bankAccount.id === bankAccountId,
  );
}

async function ownsAccount(
  accountId: string,
  clientEntityId: string,
  custodyType?: "self",
): Promise<boolean> {
  const response: globalThis.Response = await fetch(
    `${CIRCLE_API}/v1/accounts/${encodeURIComponent(accountId)}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  if (!response.ok) {
    return false;
  }
  const account: { data?: { clientEntityId?: string; custodyType?: string } } =
    await response.json();
  return (
    account.data?.clientEntityId === clientEntityId &&
    (custodyType === undefined || account.data.custodyType === custodyType)
  );
}

// Configuration and helpers.

const CIRCLE_API: string = "https://api-sandbox.circle.com";
const API_KEY: string = requireEnv("CIRCLE_API_KEY");
const FORWARDED_HEADERS: readonly string[] = [
  "content-type",
  "x-device-authorization",
  "x-registration-flow-authorization",
];
// Response headers to return. The SDK reads Link and X-Request-Id.
const RETURNED_RESPONSE_HEADERS: readonly string[] = [
  "content-type",
  "link",
  "location",
  "x-request-id",
];
// Matches "." and ".." path segments, including percent-encoded ones.
const DOT_SEGMENT: RegExp = /(^|\/)(\.|%2e){1,2}(\/|$)/i;
// Path segments under /v1/accounts that aren't account IDs.
const ACCOUNT_COLLECTIONS: readonly string[] = [
  "transfers",
  "withdrawals",
  "deposits",
  "transactions",
  "addresses",
  "auth",
];
// List filters that can widen a list beyond the account in accountId.
const LIST_FILTERS_TO_REMOVE: readonly string[] = [
  "custodyType",
  "sourceAccountId",
  "destinationAccountId",
];
const SINGLE_READS: RegExp =
  /^\/v1\/accounts\/(transfers|withdrawals|deposits|addresses\/deposit)\/[^/]+$/;

// The routes from the preceding tables. Forward nothing else.
const ALLOWED_ROUTES: ReadonlyArray<readonly [string, RegExp]> = [
  [
    "POST",
    /^\/v1\/accounts\/auth\/(loginRequests|sessions|deviceKeyRegistration)$/,
  ],
  ["GET", /^\/v1\/accounts\/auth\/context$/],
  ["POST", /^\/v1\/accounts(\/transfers|\/withdrawals|\/addresses\/deposit)?$/],
  ["GET", /^\/v1\/accounts(\/[^/]+(\/limits\/usage)?)?$/],
  ["GET", /^\/v1\/accounts\/(transfers|withdrawals|deposits)\/[^/]+$/],
  ["GET", /^\/v1\/accounts\/addresses\/deposit(\/[^/]+)?$/],
  ["GET", /^\/v1\/banks\/(wires|ach)(\/[^/]+(\/instructions)?)?$/],
];

function isAllowedRoute(method: string, path: string): boolean {
  return ALLOWED_ROUTES.some(
    ([allowedMethod, pattern]: readonly [string, RegExp]): boolean =>
      allowedMethod === method && pattern.test(path),
  );
}

// Replace with your own check that the request comes from a signed-in user of
// your application, and set res.locals.clientEntityId to that user's
// clientEntityId from your session. Until you do, the relay rejects every
// request.
function authenticateAppSession(
  req: Request,
  res: Response,
  next: NextFunction,
): void {
  const clientEntityId: string | undefined = undefined; // From your session.
  if (clientEntityId === undefined) {
    res.sendStatus(401);
    return;
  }
  res.locals.clientEntityId = clientEntityId;
  next();
}

function requireEnv(name: string): string {
  const value: string | undefined = process.env[name];
  if (value === undefined || value === "") {
    throw new Error(`Missing environment variable ${name}`);
  }
  return value;
}

import type * as Daa from "@circle-fin/daa-react-native-sdk";

const RELAY_URL: string = "https://your-backend.example.com/daa";

const backendTransport: Daa.DaaTransport = {
  async send(request: Daa.DaaHttpRequest): Promise<Daa.DaaHttpResponse> {
    const query: string = request.query === null ? "" : `?${request.query}`;
    const response: Response = await fetch(
      `${RELAY_URL}${request.path}${query}`,
      {
        method: request.method,
        // yourSessionHeaders is your own function. It returns the session
        // credential that authenticateAppSession checks on your relay.
        headers: { ...request.headers, ...yourSessionHeaders() },
        body:
          request.bodyBytes === null
            ? undefined
            : new Uint8Array(request.bodyBytes),
      },
    );

    const headers: Record<string, string> = {};
    response.headers.forEach((value: string, name: string) => {
      headers[name] = value;
    });
    return {
      status: response.status,
      headers,
      bodyBytes: new Uint8Array(await response.arrayBuffer()),
    };
  },
};