# @fntio/infra-client

A self-hosted AWS access portal, delivered as CDK stacks and constructs. Your
team signs in to a web app under your own domain, gets short-lived credentials
for the AWS accounts and roles you allow, and optionally reaches private
resources (databases, internal web servers) over a built-in VPN. Everything
runs inside your own AWS accounts.

This package is the whole product. You write one small CDK app, point it at a
typed config object, and deploy. Nothing is built on your machine: the Lambda
code is prebundled and the web app is already compiled.

- [What is in the tarball](#what-is-in-the-tarball)
- [Requirements](#requirements)
- [Install](#install)
- [Your deployment project](#your-deployment-project)
- [The config file](#the-config-file)
- [The app file](#the-app-file)
- [Deploy](#deploy)
- [Upgrade](#upgrade)
- [Decisions you make once](#decisions-you-make-once)
- [Security Hub](#security-hub)
- [Activity log](#activity-log)
- [Public API](#public-api)
- [Plugins](#plugins)
- [Plugin permissions](#plugin-permissions)
- [Bring your own web build](#bring-your-own-web-build)
- [HTTP API](#http-api)
- [License](#license)

## What is in the tarball

```
fntio-infra-client-<version>.tgz
└── package/
    ├── package.json
    ├── README.md                   this file
    ├── CHANGELOG.md                what each version changed
    ├── LICENSE                     Elastic License 2.0
    ├── openapi.yaml                the portal's HTTP API contract (OpenAPI 3.1)
    ├── dist/                       compiled stacks + constructs, with .d.ts types
    │   └── index.js                the import surface: import { ... } from "@fntio/infra-client"
    └── assets/
        ├── api/                    the portal API Lambda, prebundled
        │   ├── index.js
        │   └── vendor_modules/     its runtime dependencies (express and friends)
        ├── issuer-publish/         writes the OIDC discovery document + JWKS to the issuer bucket at deploy time
        ├── issuer-canary/          issuer health probe (alarms)
        ├── reapproval/             standing-access review sweeps
        ├── firstadmin/             creates the first admin during the deploy
        ├── federation-presignup/   SSO: Cognito pre-sign-up trigger that links a first federated sign-in to the invited user
        ├── plugin-authorizer/      plugins: the shared REQUEST authorizer on every plugin route
        ├── plugin-catalog/         plugins: writes each registered plugin's catalog record at deploy time
        ├── headscale-apikey/       VPN control-plane bootstrap
        ├── sg-manager/             VPN: per-resource security-group automation
        ├── tailnet-resolver/       VPN: in-VPC DNS for private names
        ├── keyminter/              VPN: device and connector key minting
        ├── acl-reconciler/         VPN: grants → network ACLs
        ├── invoke-relay/           VPN: the reconciler's relay to SG-managers and resolvers in another region
        └── web/                    the built web app (index.html, main-*.js, styles)
```

Every Lambda folder is a single `index.js` that CDK uploads as-is when you
synthesize. `assets/web` is served by `WebStack`; the `config.json` the app
reads at runtime is generated from your config during the deploy, so the
tarball never contains another deployment's values.

Source code (`.ts`) is not in the package. The compiled stacks in `dist/`
are readable as shipped (browse them at
[unpkg.com/browse/@fntio/infra-client/](https://unpkg.com/browse/@fntio/infra-client/));
the target-account stack a security team usually wants to read is
`dist/lib/target-account-stack.js` with `dist/lib/constructs/target-account-trust.js`.

## Requirements

- **Node.js 20 or newer** and the AWS CDK CLI on the machine you deploy from.
- **`aws-cdk-lib` 2.263 or newer and `constructs` 10.x** in your project.
  Both are peer dependencies; the install step below adds them.
- **A hub AWS account** with administrator credentials. The portal, sign-in,
  credential issuer, and optional VPN control plane deploy here.
- **A Route 53 hosted zone** in the hub account for a domain or subdomain you
  control, for example `access.acme.com`. The app, the sign-in page, the
  issuer, and the VPN all get names under it.
- **CDK bootstrap in two regions** of the hub account: your deploy region and
  `us-east-1`. CloudFront only accepts certificates and WAF web ACLs from
  `us-east-1`, so a small certificate stack always deploys there (the
  credential issuer's certificate lives in it).
- One workload account per set of roles you want to hand out, each with its
  own credentials for the deploy.

Two AWS-side approvals take up to a day. File them before the first deploy:

- **Lambda concurrency raise** in the hub account. Fresh accounts cap
  concurrent executions at 10, and the deploy's own custom resources can hit
  that.

  ```bash
  aws service-quotas request-service-quota-increase \
    --service-code lambda --quota-code L-B99A9384 --desired-value 1000
  ```

- **SES production access** in the hub account, only if you set the `email`
  block. In the SES sandbox, mail reaches verified addresses only, and the
  first-admin invite is sent during the deploy.

## Install

### From npm

```bash
mkdir acme-access && cd acme-access
npm init -y
npm install @fntio/infra-client aws-cdk-lib constructs
npm install -D typescript ts-node @types/node aws-cdk
```

Public package, no token. Pin the exact version in `package.json` if your
deployments are rolled out deliberately; `npm install @fntio/infra-client@<version>`
is the upgrade.

### From a tarball

Every version is also attached to its GitHub Release as
`fntio-infra-client-<version>.tgz` on
[FNTIO/aws-infrastructure-client](https://github.com/FNTIO/aws-infrastructure-client/releases),
for deployment repositories that vendor dependencies. Commit it and depend on
it with a `file:` spec; CI installs it like any other dependency.

```bash
mkdir vendor && cp ~/Downloads/fntio-infra-client-<version>.tgz vendor/
npm install ./vendor/fntio-infra-client-<version>.tgz aws-cdk-lib constructs
```

`package.json` then carries
`"@fntio/infra-client": "file:vendor/fntio-infra-client-<version>.tgz"`.
Upgrading is replacing the file and the version in that line; moving to the
registry is swapping the `file:` spec for a semver range.

## Your deployment project

```
acme-access/
├── package.json
├── cdk.json
├── tsconfig.json
├── bin/app.ts             the CDK app: hub stacks + one stack per workload account
├── config/project.ts      everything specific to your deployment, typed
└── vendor/                the tarball, only if you vendor it
```

`cdk.json`:

```json
{
  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
  "context": {
    "@aws-cdk/aws-iam:minimizePolicies": true,
    "@aws-cdk/core:defaultCrossStackReferences": "strong"
  }
}
```

`tsconfig.json` needs `"module": "commonjs"`, `"target": "ES2022"`,
`"strict": true`, `"esModuleInterop": true`, and `"types": ["node"]`.

## The config file

`config/project.ts` is one exported `ProjectConfig` object. Every field is
typed and documented in your editor. Values that would fail at deploy time
(a trailing dot on a zone name, an account id that is not 12 digits, an
overlapping VPC range between two sites) fail at synth with a plain error.

```ts
// config/project.ts
import * as iam from "aws-cdk-lib/aws-iam";
import { InfraClientRoles, type ProjectConfig } from "@fntio/infra-client";

const ZONE = { hostedZoneId: "Z0ABC12DEF34GH", zoneName: "access.acme.com" };

export const PROJECT: ProjectConfig = {
  projectName: "Acme Access",

  // The hub account. Explicit on purpose: nothing depends on whose
  // credentials run the synth.
  env: { account: "111122223333", region: "eu-central-1" },

  // true = tables (with point-in-time recovery and deletion protection), the
  // user pool, and the issuer signing keys are RETAINED on teardown, and every
  // hub stack gets termination protection. Use true for anything real.
  prod: true,

  // Ops alarms go here: one address or a list. AWS emails each address a
  // subscription confirmation on the first deploy. Click it or alarms go nowhere.
  alertEmail: "platform@acme.com",

  // Optional. Prefix for every by-name cross-account resource, 15 chars max.
  // SET ONCE before the first deploy; renaming later breaks all of them.
  // Default "infra-client".
  resourcePrefix: "acme-access",

  // PERMANENT. https://<domainName> is baked into every workload account's
  // trust policy. Changing it later breaks credential issuing everywhere.
  // keyVersions / signerVersion default to [1] / 1; they exist for key rotation.
  issuer: { ...ZONE, domainName: "issuer.access.acme.com" },

  // Sign-in methods. Every field is listed so none is missed; the first three
  // are the choices users see on the sign-in page.
  loginMethods: {
    password: true, // always on: Cognito requires it
    passkey: true, // Touch ID / Windows Hello / security keys; needs the `web` block
    emailOtp: true, // passwordless one-time code by email
    mfa: "optional", // TOTP on password sign-ins, "optional" | "required"; a password-only pool must set it
    threatProtection: false, // Cognito threat protection (PLUS plan, about $0.02 per active user); needs mfa
    federation: [], // your own OIDC provider(s): wiki Runbooks-Users, "Federated sign-in (SSO)"
  },

  // Created in the admins group by the deploy and emailed a set-your-password
  // link. Lowercase, a real mailbox. Bump `resend` to re-send an unclaimed invite.
  firstAdmin: { email: "you@acme.com" },

  // Optional. All portal mail (codes, invites, resets) from your own domain
  // via SES; DKIM/SPF/DMARC records are created for you. fromAddress must be
  // under zoneName. Omit to use Cognito's built-in sender (about 50/day).
  email: {
    ...ZONE,
    fromAddress: "no-reply@access.acme.com",
    fromName: "Acme Access",
    dmarcReportEmail: "platform@acme.com",
  },

  // Optional. The app on domainName, sign-in on authDomainName, which must be
  // a child of domainName. Omit to run on the CloudFront and Cognito default hosts.
  web: {
    ...ZONE,
    domainName: "access.acme.com",
    authDomainName: "auth.access.acme.com",
  },

  // Optional. WAF on CloudFront and the API. ON by default (about $26/month);
  // rateLimit = /api/* requests per client IP per 5 minutes before a 429 (one
  // office NAT is one IP, so size for the office); perTokenRateLimit = API
  // requests per bearer token per 5 minutes — a ceiling on a runaway or
  // leaked token, sized above the product's own bulk bursts.
  waf: { enabled: true, rateLimit: 5000, perTokenRateLimit: 2000 },

  // Optional. The vending API's stage throttle: requests per second across
  // EVERY caller (the per-token ceiling is waf.perTokenRateLimit). One page
  // load is 10–15 calls — size for everyone opening the portal at once.
  apiThrottle: { rateLimit: 100, burstLimit: 200 },

  // Optional. How every user's dashboard is laid out: "auto" (default) gives a
  // user the Main / Favorites / Recent sections once they hold an account an
  // admin took off the Main section; "sections" or "plain" for everyone.
  dashboard: { layout: "auto" },

  // Optional. How long the activity log keeps each row (30–3650 days).
  // Default 400, which outlasts the yearly access review.
  audit: { retentionDays: 400 },

  // First impression only. Admins can restyle in the app afterwards.
  // brandShow: "logo" | "project" | "company" | "logo-and-project" | "logo-and-company".
  branding: {
    logoUrl: "https://acme.com/logo.svg", // or logoFile: "assets/logo.svg", a local file (no public URL)
    primaryColor: "#0E7490",
    accentColor: "#F59E0B",
    companyName: "Acme",
    brandShow: "logo-and-project",
  },

  // The roles users can get, per workload account. Deployed by
  // TargetAccountStack (see the app file) and registered in the portal's
  // Accounts page. Role names are pinned into trust policies: never rename.
  rolesByAccount: {
    "444455556666": [
      InfraClientRoles.READ_ONLY,
      InfraClientRoles.FULL_ADMIN,
      {
        ...InfraClientRoles.READ_ONLY,
        roleName: "InfraAuditor",
        description: "Read-only for the external audit team.",
      },
    ],
    "777788889999": [
      {
        roleName: "BillingViewer",
        managedPolicies: [
          iam.ManagedPolicy.fromAwsManagedPolicyName("job-function/Billing"),
        ],
      },
    ],
  },

  // Optional. The private network. Omit it and no VPN stack deploys and the
  // portal shows no Network pages. One site = one routing domain; most
  // deployments need exactly one. Site ids are PERMANENT once a device enrolls.
  network: {
    ...ZONE,
    subdomain: "network", // sites live at <site>.network.access.acme.com
    // containerInsights: true, // CloudWatch Container Insights on the VPN cluster; defaults to `prod`
    sites: {
      main: {
        displayName: "Acme",
        // Every account belongs to exactly one site.
        accounts: ["444455556666", "777788889999"],
        // Accounts allowed to run a connector (machine keys only).
        connectorAccounts: ["444455556666"],
        // VPCs joined by ConnectorStack, keyed by account. Drives the deploy
        // and the per-site CIDR overlap check. Add `region` for a VPC outside
        // the hub's region.
        connectorVpcs: {
          "444455556666": { vpcId: "vpc-0abc1234def567890", routes: ["10.20.0.0/16"] },
          // Several VPCs in one account: a list, every entry but one named — the
          // name suffixes that connector's hostname, stack id and function names.
          // "444455556666": [
          //   { vpcId: "vpc-0abc1234def567890", routes: ["10.20.0.0/16"] },
          //   { vpcId: "vpc-0def5678abc123456", routes: ["10.50.0.0/16"], name: "sandbox" },
          // ],
        },
        // Private DNS names resolved inside that VPC (its resolver = CIDR base + 2).
        splitDns: { "corp.internal": ["10.20.0.2"] },
      },
    },
  },
};
```

The blocks at a glance:

| Block | Required | Changeable later | What it controls |
| --- | --- | --- | --- |
| `projectName`, `env`, `prod`, `alertEmail` | yes | `prod` and `alertEmail` yes; `env` no | Identity of the deployment |
| `resourcePrefix` | no | **no** | Names of every cross-account resource |
| `issuer` | yes | **no** (`keyVersions`/`signerVersion` yes) | The credential issuer host every account trusts |
| `loginMethods` | yes | yes | Password, passkey, email code, TOTP second factor, threat protection, federated sign-in |
| `firstAdmin` | no | yes | The admin account the deploy creates |
| `email` | no | yes | Portal mail from your own domain |
| `web` | no | add yes; change or remove **no** in practice | Custom app and sign-in domains; also the passkey relying-party id (a change orphans every registered passkey) and the us-east-1 certificate `WebStack` imports across regions |
| `waf` | no | yes | Web ACLs on CloudFront and the API |
| `audit` | no | yes (rows already written keep their retention) | Activity-log retention |
| `branding` | yes (may be `{}`) | yes | Logo and colors until an admin restyles in-app |
| `rolesByAccount` | yes | add yes, rename **no** | Roles per workload account |
| `network` | no | add sites yes, rename site ids **no** | The VPN |
| `plugins` | no | yes (remove registrations one deploy before turning it off) | The customer-plugin runtime |

## The app file

`bin/app.ts` turns the config into stacks. The hub stacks and one small stack
per workload account live in the same app; deploys pick stacks by name and
run with that account's credentials.

```ts
// bin/app.ts
import { App } from "aws-cdk-lib";
import {
  addAccessPortal,
  AccessPortalHub,
  ConnectorStack,
  DEFAULT_RESOURCE_PREFIX,
  resolveSites,
  TargetAccountStack,
} from "@fntio/infra-client";
import { PROJECT } from "../config/project";

const app = new App();
const resourcePrefix = PROJECT.resourcePrefix ?? DEFAULT_RESOURCE_PREFIX;
const { account, region } = PROJECT.env;

// Validates the sites (slugs, one site per account, CIDR overlap) and fails
// the synth with the reason. Required whenever `network` is set.
const sites = PROJECT.network ? resolveSites(PROJECT.network) : undefined;

// The hub: DataStack, CredsStack, WebCertStack (us-east-1), WebStack, and
// NetworkStack when `network` is set. Deploy these with hub credentials.
addAccessPortal(app, { project: PROJECT, resourcePrefix, sites });

// The same hub as cross-account stacks see it: every well-known name and ARN
// derives from these attributes, so you never assemble one by hand.
const hub = AccessPortalHub.fromAttributes({
  account,
  region,
  resourcePrefix,
  issuerDomain: PROJECT.issuer.domainName,
  network: PROJECT.network
    ? { zoneName: PROJECT.network.zoneName, subdomain: PROJECT.network.subdomain }
    : undefined,
});

// One stack per workload account: an OIDC provider trusting the hub's ISSUER
// (never the hub account) plus the listed roles. Nothing else. Deploy each
// with that account's credentials.
for (const [targetAccount, roles] of Object.entries(PROJECT.rolesByAccount)) {
  new TargetAccountStack(app, `AccessTarget-${targetAccount}`, {
    env: { account: targetAccount, region },
    issuerUrl: hub.issuerUrl!,
    roles,
  });
}

// One stack per connector VPC (VPN only). The site decides its control plane
// and which key minter it may call.
for (const site of sites ?? []) {
  for (const [connectorAccount, vpcs] of Object.entries(site.connectorVpcs)) {
    for (const vpc of vpcs) {
      const suffix = vpc.name ? `-${vpc.name}` : "";
      new ConnectorStack(app, `Connector-${connectorAccount}${suffix}`, {
        env: { account: connectorAccount, region: vpc.region ?? region },
        hub,
        site: site.id,
        vpcId: vpc.vpcId,
        routes: [...vpc.routes],
        name: vpc.name,
      });
    }
  }
}
```

Prefer to build the IAM roles yourself? Skip `TargetAccountStack`: create the
provider once with `createIssuerProvider(scope, id, issuerUrl)` and use
`webIdentityPrincipal(provider, roleName)` as `assumedBy` on any `iam.Role`.
The role's `roleName` must equal the name passed to `webIdentityPrincipal`;
the trust policy pins it. The same applies to the VPN: `TailnetConnector` and
`SgManager` compose into a stack you already own instead of `ConnectorStack`.

## Deploy

### 1. Bootstrap the hub account, both regions

```bash
export AWS_PROFILE=acme-hub
npx cdk bootstrap aws://111122223333/eu-central-1
npx cdk bootstrap aws://111122223333/us-east-1
```

### 2. Deploy the hub

Deploy by name. `--all` would also try the workload-account stacks with the
wrong credentials.

```bash
npx cdk deploy DataStack CredsStack WebStack            # WebCertStack deploys as a dependency
npx cdk deploy NetworkStack                             # only with a `network` block
```

The first run takes 15 to 30 minutes; certificate issuing and DNS dominate.
While it runs, confirm the SNS subscription that lands in `alertEmail`.

When it finishes, read the outputs:

- `CredsStack.FirstAdminInviteSent`: `sent` means check the first admin's
  inbox (the link is valid 7 days). `suppressed` means the account exists but
  the mail could not go out, almost always SES still in its sandbox; get
  production access or verify the address, then bump `firstAdmin.resend` and
  redeploy. `already-active` means nothing to do.
- `WebStack.WebUrl`: your portal.

Sign in. The first admin is offered a theme wizard; anything set there
overrides the deploy-time `branding` without a redeploy.

### 3. Connect a workload account

```bash
export AWS_PROFILE=acme-sandbox
npx cdk bootstrap aws://444455556666/eu-central-1        # once per account
npx cdk deploy AccessTarget-444455556666
```

Then, in the portal as an admin: **Accounts → Add account** with the account
number and a friendly name, and add the roles you just deployed. Role names
must match `rolesByAccount` exactly; the portal cannot verify them across
accounts. Grant yourself one role, click **Get credentials** on its card, and
run `aws sts get-caller-identity`. It should report the workload account.

### 4. Join a VPC to the VPN (optional)

```bash
export AWS_PROFILE=acme-sandbox
npx cdk deploy Connector-444455556666
```

The connector looks the VPC up at synth, so the command needs credentials for
that account. A VPC outside the hub's region (`connectorVpcs.<account>.region`)
deploys there, so bootstrap the account in that region first
(`npx cdk bootstrap aws://444455556666/eu-west-1`). An account's second VPC
carries a `name` in config and deploys as `Connector-444455556666-<name>`.
Back in the portal, register private resources (host and port)
on the **Network** page and grant them like roles. End users click
**Connect**; a guided setup installs the standard Tailscale client on first use.

### Tear down

`npx cdk destroy` per stack, in reverse order. With `prod: true` every hub
stack has termination protection and the VPN load balancer has deletion
protection, so lift both first:

```bash
aws cloudformation update-termination-protection --no-enable-termination-protection --stack-name <stack>
aws elbv2 modify-load-balancer-attributes --load-balancer-arn <arn> --attributes Key=deletion_protection.enabled,Value=false
```

The tables, user pool, and signing keys are retained and must be deleted by
hand (tables keep deletion protection until you turn it off), and so is the
VPN control plane's EFS file system (Headscale state): delete its mount
targets, then the file system. A removed VPN site also leaves its API-key
secret (`<prefix>/headscale-apikey-<site>`) in Secrets Manager on purpose;
delete it once nothing uses that site.

## Upgrade

```bash
npm install @fntio/infra-client@<version>                # vendored: replace the .tgz and the file: spec, then npm install
npx cdk diff DataStack CredsStack WebStack               # review before anything changes
npx cdk deploy DataStack CredsStack WebStack
```

Deploy the hub stacks together. The web app and the API version together, and
if one stack fails partway, some admin pages error until the failed stack
deploys cleanly. Browsers and the desktop app can keep an old web bundle
cached for a while; desktop users quit from the tray icon and relaunch.

Workload-account stacks rarely need redeploying. Their job is deliberately
frozen so hub upgrades do not cascade into every account. Redeploy one when
you add or change its roles.

### Upgrading to 0.1.17 — the activity log and pop-up notifications

Nothing to migrate: older vend rows are read in the new shape. The deploy
adds one index to the audit table (`byActor`); it rides the normal hub
deploy. The reconciler writes VPN session, firewall-rule and connector rows
only after a manual `NetworkStack` deploy (it needs the table and the
retention in its environment). Set `audit.retentionDays` if the 400-day
default is not what your policy says; rows already written keep the
retention they were written with. Desktop users get the pop-up changes
(Windows toasts, click-to-open, wake refresh, VPN-drop notice) with the next
desktop build; the web app works with older shells.

### Upgrading to 0.1.16 — several connector VPCs per account

`connectorVpcs.<account>` may be a list, every entry but one carrying a
`name`. A single VPC per account needs nothing. Deploy `NetworkStack` first
(its reconciler now addresses each VPC's SG-manager and resolver by name), and
when an account gains a second VPC redeploy its existing `Connector-<account>`
alongside the new `Connector-<account>-<name>`: the existing SG-manager learns
which VPC is its own and answers `other-vpc` for groups elsewhere.

### Upgrading to 0.1.8 — the issuer moves onto CloudFront

The credential issuer (`https://issuer.<your zone>`) is served from a
private S3 bucket behind CloudFront instead of an API Gateway HTTP API. The
hostname, the signing keys and every workload account's trust are unchanged;
the deploy migrates in one CloudFormation update (new endpoint first, DNS
flipped in place, the API deleted last — about 15 minutes). Before you
deploy it:

- `us-east-1` must be CDK-bootstrapped in the hub account even if you run
  without `web` and with WAF off — the issuer's certificate now lives in
  the us-east-1 companion stack. Step 1 of "Deploy" covers it.
- Do not combine it with a `keyVersions` / `signerVersion` change.

After it: fetch `https://issuer.<your zone>/.well-known/openid-configuration`
and `…/.well-known/jwks.json`, then get credentials for one role from the
portal — that is the real proof (STS read the new JWKS). Delete the old
regional ACM certificate if CloudFormation left it behind, and suppress the
new CloudFront.17 finding for the issuer distribution if you run Security
Hub ("Security Hub" below). With WAF on, a third web ACL `<prefix>-issuer`
appears — observe-only, it never blocks, about $8/month.

## Decisions you make once

| Value | Where | Why it is permanent |
| --- | --- | --- |
| Issuer hostname | `issuer.domainName` | In every workload account's trust policy |
| Resource prefix | `resourcePrefix` | Names every cross-account resource |
| Role names | `rolesByAccount[*].roleName` | Pinned into each role's trust condition |
| VPN site ids | keys of `network.sites` | The login hostname of every enrolled device and connector |
| Hub account and region | `env` | Everything else derives from it |

Everything else — branding, login methods, the list of sites and VPCs —
changes with a redeploy. The app's own web address (`web`) can be added
later, but changing or removing it orphans registered passkeys (see the
config table).

## Security Hub

Deployments pass the AWS Foundational Security Best Practices controls that
apply to their resources by construction, or with `prod: true`. A few are
deliberate cost trade-offs or by-design exceptions (CloudFront distributions
without origin failover or signed-URL key groups) that you suppress once per
account. The source repository's runbook lists every control and its status
under "Security posture" in the deployment README.

## Activity log

Every action that changes or uses access writes one row to the audit table:
who did it (a person, a service user, or `system:reapproval`,
`system:reconciler`, `system:deploy`, `system:expiry`), the action
(`object.verb`: `role.grant`, `request.approve`, `credentials.vend`,
`vpn.connect`, `admin.access`, …), whom or what it was about, the outcome
(`OK`, `DENIED`, `FAILED`) and a caller-safe reason. Group, cascade and bulk
changes also write derived rows per affected person (`access.gain`,
`access.lose`) from the same effective-access diff that produces the bell's
notices, linked to the primary row by a batch id — one per target, or one
per person carrying a `count` when a group or cascade change moves more than
five targets for them (the same threshold bundles the bell notice). The actor is bound per
request by the auth middleware and per job by the Lambda entry point; services
never take an actor parameter, so a row cannot name the wrong identity.

The log is advisory: nothing reads it to decide access. It is read by the
Activity page (`GET /admin/audit`, filters and a time cursor), by the yearly
review for a role's usage count, and by the setup checklist. Retention is
`audit.retentionDays` (30–3650, default 400). VPN sessions, firewall rules
and connector changes come from the reconciler's five-minute pass (five-minute granularity,
derived from Headscale's online state, so they cover every client). Refused
admin calls and refused plugin calls are rows too; anonymous 401s, reads and
preferences are not, and neither is a catalog or branding save that changes
nothing. A direct revoke whose access continues through a group names the
group(s) on its row. Name lists on a row (`affected`, `unchanged`) stop at 50
entries with the full count kept — the per-user rows carry every person;
reasons are cut at 300 characters and notes at 500. `GET /admin/access-report`
exports the current state the log explains: one CSV row per person and target
they hold.

## Public API

Everything a consuming CDK app needs is exported from the package root. Deep
imports into `dist/` are not part of the contract.

| Export | Kind | Use |
| --- | --- | --- |
| `ProjectConfig`, `SiteConfig` | types | Your config file |
| `addAccessPortal(scope, props)` | function | The hub stacks, written into your app |
| `AccessPortalHub.fromAttributes(attrs)` | class | The hub as cross-account stacks see it: `issuerUrl`, `controlUrl(site)`, `connectorKeyMinter(scope, site)`, `aclReconcilerPrincipal()`, `aclReconcilerRelayPrincipal()` (what an SG-manager or resolver outside the hub's region trusts) |
| `resolveSites(network)` | function | Validated, deploy-ready sites for `addAccessPortal` and `ConnectorStack` |
| `TargetAccountStack` | stack | Trust plus roles in a workload account |
| `InfraClientRoles`, `TargetRoleSpec` | constants, type | `READ_ONLY`, `POWER_USER`, `FULL_ADMIN`; plain data you can spread and tweak |
| `createIssuerProvider`, `webIdentityPrincipal` | functions | Hand-built roles trusting the issuer |
| `ConnectorStack` | stack | One VPC joined to the VPN (`name` tells an account's second VPC from its first) |
| `TailnetConnector`, `SgManager`, `TailnetResolver` | constructs | The connector pieces for a stack you already own |
| `DataStack`, `CredsStack`, `WebStack`, `WebCertStack`, `NetworkStack` | stacks | The hub stacks individually, if you need to reach into one |
| `WebAcl`, `WafConfig`, `WafLimits` | construct, types | The WAF pieces |
| `DEFAULT_RESOURCE_PREFIX`, `assertValidResourcePrefix`, the `*FnName` and `*RoleName` helpers | constants, functions | The raw by-name contracts, for consumers who need the names |

Opinionated only where the security model requires it: the trust conditions
(`aud` plus a role-scoped `sub` pin), role name equals the pinned name, the
`connector-<account>[-<name>]` hostname contract, and the well-known resource names.
Everything else is ordinary CDK. `TargetRoleSpec.maxSessionDuration` defaults
to 12 hours; the per-role session length an admin sets in the portal is the
effective limit.

## Personal access tokens

With `personalAccessTokens: { enabled: true }` every user can create tokens for scripts, CI jobs,
command-line tools and remote development machines that act as them. The bearer token is
`icpat_<tokenId>_<secret>`; the prefix lets secret scanners recognise a leaked one. The portal
stores only the SHA-256 of the secret (the `TokensTable` in `DataStack`, always present so the
switch never moves an export) and shows the secret once, at creation.

- **Scopes.** `aws` lists the owner's accounts and roles and vends credentials (`GET /accounts`,
  `POST /credentials`, console links); `network` enrolls the owner's own devices (`POST
  /network/device-key`, optionally `ephemeral`) and lists or removes them (`GET /network/devices`,
  `DELETE /network/devices/{site}/{name}`); `shares` creates, lists and stops dev shares; `api` is
  every route the owner may call, admin routes included only while the owner is an admin. The
  table of which scope reaches which route is `lambdacode/api/services/tokenScopes.ts`; anything
  else answers `403` with `code: "TOKEN_SCOPE"`.
- **Acts as its owner.** A request with a token sees the owner's current effective access (a lost
  grant is lost for the token at once), narrowed in `access.ts` to the token's optional role subset
  (`roles`, for `aws` and `api`). Admin status and the owner's account status are read from the
  directory, cached for a minute, never from the token; a disabled or deleted owner's tokens stop
  working, and deleting a user deletes their tokens.
- **Never self-perpetuating.** No token can create, list or revoke tokens (`/tokens`,
  `/admin/tokens`); that needs a signed-in session. `GET /tokens/current` answers any token with
  who it acts as. Plugin routes refuse tokens (the plugin authorizer has no token table).
- **Lifetime.** Every token expires; `personalAccessTokens.maxLifetimeDays` caps it (default 90,
  1–365). The bell warns before the end and once after, like temporary grants.
- **Revocation** deletes the row, and every request reads it strongly consistent, so it takes
  effect on the next call. Admins list and revoke every user's tokens (Users → Access tokens).
- **Audit.** Every activity row written while acting through a token carries `actor.token`
  (`{ id, name }`).

Turning it on is a config change plus a deploy of `DataStack CredsStack WebStack`; the device list
and delete routes also need a `NetworkStack` deploy (the device minter answers them).

## Plugins

Customer plugins are small apps a deployment bolts onto the portal: a
frontend of any framework shown in an iframe, Lambda routes behind the
portal's authorizer, and two permission levels (`user`, `admin`) granted from
the usual Users and Groups screens. The permission rules are in
[Plugin permissions](#plugin-permissions); this section is the deploy side.

**Trust model, before turning it on.** A plugin page is served from the
portal's own origin and framed without a sandbox (the design the epic
chose so the page can use the portal's session directly). That means an
installed plugin runs with the signed-in user's full authority: it could
read the portal's tokens, call any core API as that user, and on the
desktop reach the shell bridge. The `user`/`admin` permissions decide who
sees a plugin, not what its code may do. Install plugins you would trust
with the portal bundle itself, and review their dependencies the same way.
A Content-Security-Policy on `/plugin-assets/*` lets a plugin page load
from and talk to the portal only (no third-party scripts, no sending data
elsewhere); the app pages send their own enforced policy (the portal, the
region's Cognito API and the hosted-UI domain).

**Turn the feature on** with a `plugins` block in the config:

```ts
plugins: { enabled: true },            // discoveryRefreshSeconds: 60 by default (15–300)
accountDimensions: { enabled: true },  // tenant/project/stage off account names; labels + stage map optional (wiki: Configuration Reference)
```

`enabled: true` creates the `/api/plugins/…` route tree on the core API (the
core keeps every other `/api/*` path), the `/plugin-assets/*` CloudFront
behavior (same-origin framing allowed, no SPA rewrite), the discovery
settings the portal reads, and, per registered plugin, the asset upload and
the catalog record. Off or absent: none of that exists, and any plugin
permission rows stay dormant. The catalog table itself always exists, so
flipping the flag never adds or removes a cross-stack export. Registrations
passed while the flag is off fail at synth.

**Register a plugin** by passing `definePlugin(...)` results (from
`@fntio/infra-client-plugin-cdk`) to `addAccessPortal`:

```ts
addAccessPortal(app, { project, resourcePrefix, plugins: [parameters] });
```

Composing the stacks yourself? `resolvePlugins`, `PluginApi` and `PluginCatalogActivation` are exported; all
three live on the CredsStack side.

**What a deploy does, in order.** Handler factories run inside CredsStack and
each route becomes a gateway method under
`/api/plugins/<id>/accounts/{accountNumber}<path>`; the plugin's resource
carries the shared REQUEST authorizer as its default, so every method under it
is authorized by construction (result cache 0). The UI uploads to the plugin-assets bucket
(DataStack) under `<id>/<version>-<hash>/`, served as `/plugin-assets/…`; the
hash is the content hash, so changed bytes under the same version get a new
URL, and earlier revisions are never pruned. Last, a
`Custom::PluginCatalogRecord` in CredsStack writes the catalog row, after the
upload, the API stage and the plugin's methods. Because it depends on the
methods, CloudFormation also tombstones it *before* removing them. Rollback of
a failed activation restores the previous record through the same provider.

One routing fact to know. Express owns `/api/plugins` (every verb) and any
path under it that no registered method claims — an unknown plugin id, and an
unmatched path under a registered one, both reach the core app and get its
JSON 404. A plugin's handler is reachable only through a method it registered,
which is what stops an unknown route touching plugin code.

**Authorization.** The shared REQUEST authorizer
(`lambdacode/plugins/authorizer.ts`) runs on every plugin method with a zero
result cache. It verifies the bearer token with the verifier Express uses
(`services/tokenVerifier.ts`: a Cognito ID token for people; an access token
with the service scope plus a live registry row for service users, read
strongly consistently through `services/serviceUserRegistry.ts`), resolves the route
from the catalog by method and gateway resource template, takes the account
from the `{accountNumber}` path parameter, and asks `checkPluginPermission`.
Nothing the client names is trusted. Missing or invalid credentials: 401.
Authenticated but no available grant, an unknown route or method, a
malformed account or resource, a disabled or removed plugin: 403 (a `Deny`
on the invoked method ARN; `context.reason` says why). Signing keys or a
table unreachable: the gateway's 5xx. None of the three invokes the handler.
An allow is scoped to the exact method ARN and carries the typed context
(`PluginAuthorizerContextV1`: plugin, revision, route, account, required
permission, subject, principal type, correlation id), never a token. Every
decision is one JSON line in the authorizer's log group. Revocation limits:
a check that begins after a revoke completed sees it; a request already
authorized finishes; an accepted job runs until the plugin's own cancellation
rules stop it; there is no atomic snapshot across unrelated concurrent grant
edits.

Two more limits worth knowing. A deploy that adds a route makes the gateway
method live before the catalog record naming it: calls to the new route answer
403 `route-unknown` until the activation resource completes, which is why the
UI that uses a new route ships in the same deploy rather than ahead of it. And
the authorizer only reads, so a service user that calls nothing but plugin
routes never advances its `lastUsedAt`; the access reviews see it as unused
even while it works.

**Update, disable, remove, reinstall.** Changing the definition rewrites the
record with a new revision. `enabled: false` on a plugin keeps everything but
suppresses discovery and denies calls. Removing the registration tombstones
the record (labels kept, grant rows kept, holders noticed), then the routes
and assets go. Registering the same id again restores still-valid grants on
purpose. Records are owned by the CloudFormation stack that wrote them; a
different stack claiming an installed id fails the deploy with "already
installed by …" — if that is you after moving the activation to another stack,
delete the row from the catalog table by hand (`aws dynamodb delete-item`) and
redeploy. To switch the whole feature off, remove the registrations first (one
deploy), then set `enabled: false`; the table and bucket stay, with their
exports, so that second deploy cannot fail on an export in use.

**Handlers and IAM.** Plugin Lambdas live in the hub account and region and
run under the execution role you give them; core grants decide who may call
a route, your IAM decides what the handler may touch. Every Lambda that reads
the catalog also gets the Accounts table name and read access (the API
handler, the reapproval sweeper, the catalog provider) — `pluginRuntimeEnv`
and `grantPluginRuntimeRead` are exported for custom compositions.

**Packaging.** The compiled stacks import `@fntio/infra-client-plugin-sdk`,
which ships inside this package's tarball (bundled dependency), so a vendored
tarball install keeps working with no second package to fetch. A
plugin author's own code imports the SDK directly, so they install the plugin
tarballs too: every GitHub Release from v0.1.18 carries them beside this one.

### Troubleshooting

Five failures seen so far, each with its cause and the fix.

- **A route answers 403 with `context.reason` `route-unknown` while a deploy
  runs.** The gateway method goes live before the catalog record that names
  it (the activation resource depends on the methods, so it is written last).
  Wait for the deploy to finish; ship the UI that calls a new route in the
  same deploy as the route, never ahead of it.
- **Plugin assets answer 403.** `/plugin-assets/*` is CloudFront over the
  private assets bucket with a GetObject-only policy and no SPA rewrite, so a
  key that does not exist answers 403 — a real error, never `index.html`. The
  object key must equal the URL path: the usual cause is a plugin registered
  with its frontend not built (an empty or stale `ui.assets` directory) or an
  `entry` that names a file outside it. Build the frontend before synth and
  redeploy.
- **"This plugin was built for a different version of the portal."** The
  frame speaks another message protocol version than the installed portal
  (0.1.x pages against a 0.2.0 portal, or the reverse). Rebuild the plugin
  against the plugin packages of the installed `@fntio/infra-client` version
  and redeploy; see the SDK README's Versioning section.
- **"Its page loaded but never connected to the portal"** (the handshake
  timeout). The page never posted `ready`: the `entry` path names the wrong
  file, or the plugin-assets Content-Security-Policy blocked a script the
  page needs — that policy allows the portal only, so a bundle that loads
  anything from a third-party host never runs. Open the frame URL in a tab
  and read the console for CSP violations; bundle every dependency.
- **Token refresh fails inside a frame.** The host owns the session; the
  SDK never signs in itself. After an authentication-layer 401 it asks the
  host to renew and retries exactly once; if that fails, the plugin surfaces
  the error and the portal's own session-end flow applies (`sessionEnded`
  with reason `expired` at the 12 h wall). A plugin Lambda that answers 401
  for a business failure triggers the same retry, so answer domain 4xx codes
  instead.

## Plugin permissions

Customer plugins (Epic 5) hold their grants in the same Access table as roles,
as `plugin#<pluginId>#<accountNumber>#<user|admin>` rows on users and groups.
What such a row *means* is decided in one place, `lambdacode/api/services/pluginAccess.ts`:

- **Availability.** A row authorizes only while the plugin's catalog record is
  installed and enabled, the permission is declared by the plugin, and the
  account is both bound by the plugin and registered in the Accounts catalog.
  A row that fails any of these is *dormant*: visible and revocable in the
  grant editor, never authorizing, never renewable.
- **Implication.** `admin` includes `user` only when the plugin declares
  `user`. It is applied when capabilities are derived, never stored, so an
  admin grant is stored as admin and a user capability may cite it.
- **No bypass.** App admins and service users are ordinary principals here;
  a service user's grants live on its own `user#<clientId>` rows.
- **Notices.** Loss notices for plugins diff *available capabilities*, not
  rows: revoking a user row while an admin row still implies it is silent;
  a plugin going dormant is a `PLUGIN` revocation (`via: CASCADE`).
- **Retention.** Removing or disabling a plugin keeps its rows so that
  re-enabling or reinstalling the same id deliberately restores still-valid
  access; deleting an account removes that account's plugin rows (with
  notices) like the role cascade does. The yearly review sweep raises
  reviews only for available rows, but a review already open on a row that
  went dormant still lapses, and approving a review of a dormant row is
  refused (409).
- **Reads on the authorization path** are strongly consistent (catalog,
  accounts, access), with unprocessed batch keys retried a bounded number of
  times and never read as "no grant".

**Two discovery views, on purpose.** `GET /api/plugins` answers the signed-in
caller: only plugins where they hold an available capability, only the UI
entries whose own permission is available somewhere, and account names from the
Accounts catalog, so someone holding nothing but a plugin grant still sees the
account. It is per-caller and never cached. `GET /api/admin/plugins` answers the
grant editor: every definition, including disabled, unavailable and tombstoned
ones, independent of the admin's own plugin grants, so a binding nobody holds
yet is still assignable. Neither returns handler internals, and an empty list
always means empty — a storage failure is an error, never a fabricated empty
catalog.

**Assignment and review operations.** Admins assign and revoke on
`/api/admin/plugins/{pluginId}/accounts/{accountNumber}/grants`: `PUT` with a
principal (`{kind:"user",userId}` or `{kind:"group",groupId}`), a permission and
an optional `durationHours` for users; `DELETE` with the principal and
permission. Both are idempotent. Assignment refuses an unavailable binding (409),
an unknown plugin or unbound account (404), and an undeclared permission or a
group expiry (400). Revocation is unconditional on purpose, so a stale row on a
disabled or removed plugin stays removable. A user's plugin access has its own
view, `GET /api/admin/users/{userId}/plugin-grants`, alongside the resource-grants
one; a group carries its plugin references in the groups list. Either way one call
covers every plugin, so no page sweeps per-plugin endpoints, and a plugin problem
never takes a user's role grants down with it. Plugin rows join the
existing yearly review lifecycle: reviews are raised only for available rows,
approving a review of a dormant row is refused (409), and losing a capability
produces the usual revocation notice.

The catalog is deployment-written; how it gets there is [Plugins](#plugins).

## Bring your own web build

`addAccessPortal` accepts `webAssetPath`, a directory with an `index.html`,
to serve a web bundle other than the one baked into the package. The deploy
still generates `config.json` from your config, so the bundle must be a build
of this product's frontend, not an arbitrary site.

## HTTP API

`openapi.yaml` in the package root describes every route of the portal API
(OpenAPI 3.1): the token kinds (a Cognito ID token for people, a
`client_credentials` access token for service users, who are admins, and
personal access tokens),
request and response shapes, and status codes. The route inventory is
drift-tested against the mounted routes in the package's test suite; the
shapes are maintained by hand alongside the code. Requests go to
`https://<web domain>/api/…`.

## License

Elastic License 2.0. Commercial use is allowed; offering the product to
third parties as a managed or hosted service is not.
