generate_auth_docs.ts

/**
 * This script generates diagrams for each authorization group defined in
 * (./auth.ts).  The diagrams illustrate the authentication query plan that will
 * be generated for each table in the database, for each group.
 *
 * These diagrams provide a visual representation of the authentication flow to
 * help the developer understand what is happening.
 */
import { saveAuthDiagram } from './api/utils/diagram';
import { tables } from './api/relationships';
import { groups } from './auth';

// eslint-disable-next-line @typescript-eslint/no-var-requires
const fs = require('fs');
// eslint-disable-next-line @typescript-eslint/no-var-requires
const { execSync } = require('node:child_process');

let markdown = `
# Data Authorization

> Notice: This file is automatically generated by
> [generate_auth_docs.ts](../graphql/generate_auth_docs.ts).

Below you will find various diagrams that illustrates how to API restricts
access to data.

## How it works

This project is hosted behind an Azure API gateway that determines what data
can be returned by a given client via [subscriptions](https://learn.microsoft.com/en-us/azure/api-management/api-management-subscriptions).  Each subscription is tied to a
*product* which modifies the \`x-auth-group\` header sent to this service.  The
available values and filters are defined in the [auth.ts](../graphql/auth.ts)
file.

\`\`\`javascript
// auth.ts
${JSON.stringify(groups, null, 2)}
\`\`\`

### Authorization flow

The process described above is illustrated below using a flow chart.

![Authorization flow chart](auth.flowchart.svg)

## SQL Query modifications

When the GraphQL server receives a request to access data in a particular table,
the foreign key relationships of the table are examined, and a query plan is
produced that enforces the rules declared in [auth.ts](../graphql/auth.ts).

The diagrams below illustrates what the resulting query plan is for each group
and table combination.

`;

execSync('xvfb-run -a diagrams build docs');

const all_groups = Object.keys(groups);
all_groups.forEach((grp) => {
  const basedir = `docs/${grp}`;
  if (!fs.existsSync(basedir)) fs.mkdirSync(basedir);
  console.log(`Generating diagrams for "${grp}" --->`);
  process.stdout.write('  ');
  tables.forEach((table, i) => {
    markdown += `
### ${grp} -> ${table}

![${grp} ${table} query flow](${grp}/${table}.dot.svg)

`;
    process.stdout.write(`${table}${i < tables.length - 1 ? ', ' : ''}`);
    saveAuthDiagram(
      { authenticated: true, filters: groups[grp] },
      table,
      `${basedir}/${table}.dot`
    );
  });
  console.log('\n');
  execSync(`xvfb-run -a diagrams build ${basedir}`);
  tables.forEach((table) => {
    fs.unlinkSync(`${basedir}/${table}.dot`);
  });
});

fs.writeFileSync('docs/AUTHORIZATION.md', markdown);

console.log('Done.');