Repository navigation
Architecture
@fntio/infra-client is a self-hosted AWS access portal delivered as one npm package: CDK stacks and constructs, prebundled Lambdas, and the compiled Angular web app. A consumer writes a small CDK app, points it at a typed config object, and deploys into their own AWS accounts. Users sign in under the consumer's own domain, receive short-lived credentials for the accounts and roles they are allowed, and optionally reach private VPC resources over a built-in VPN. This page maps the deliverables, the stacks, the credential vending flow, the data model, the API surface, and where the code lives. Access decisions are covered in Access Model, the VPN in Private Network, and trust and hardening in Security Posture.
| Deliverable | Repo path | Ships as |
|---|---|---|
The package @fntio/infra-client
|
packages/infra-client/, plus the frontend/ build copied into assets/web at pack time |
An npm tarball (a registry at general availability): compiled dist/, one prebundled folder per Lambda under assets/, the built web app, openapi.yaml, the package README |
| The desktop client | desktop/ |
One public signed Electron binary for all deployments, attached to each GitHub Release by the release workflow (desktop-build cuts test builds). Not in the package |
| FNTIO's own deployment | infra/ |
config/project.ts, bin/app.ts, the internal-only PipelineStack, TestbedStack and DemoVpcStack, the onboarding import CLI, the ops runbooks. Not in the package; moves to a private repo before the source-available release |
Also in the repo but not shipped: samples/ (five consumer-voice CDK apps the package README's examples derive from) and .github/workflows/ (release.yml, desktop-build.yml and the repo automation). Consumer documentation is the package README, which ships inside the tarball: What is in the tarball.
Nine CDK stacks. The hub account hosts the portal; each workload account gets a trust stack and, optionally, a VPN connector per VPC. The package exports the hub stacks, TargetAccountStack and ConnectorStack; PipelineStack and TestbedStack live in infra/lib/ and are FNTIO-only.
| Stack | Deploys to | Holds |
|---|---|---|
DataStack |
hub | The DynamoDB tables (below). Kept apart from compute so data outlives any API redeploy |
CredsStack |
hub | The Cognito user pool (Essentials plan, choice-based sign-in, the admins group, the api resource server); the OidcIssuer construct (KMS RSA signing keys, with the discovery document and JWKS as static S3 objects behind CloudFront on the stable issuer host); the VendingApi construct (Express on Lambda, Node 22, behind a LambdaRestApi proxy that also serves the public GET /.well-known/infra-client discovery document); the daily ReapprovalSweeper Lambda; the API web ACL |
WebStack |
hub | The Angular app in a private S3 bucket behind CloudFront (Origin Access Control), SPA deep-link rewrite, the SPA's Cognito app client and the custom auth domain. Outputs WebUrl
|
WebCertStack |
hub, us-east-1 | What CloudFront only accepts from that region: the issuer certificate (always), the web and auth-domain certificate (with web), the CloudFront WAF web ACLs. Never deployed alone; a dependency of CredsStack and WebStack, so it exists on every deployment |
TargetAccountStack |
each workload account | An IAM OIDC provider trusting the issuer plus one fixed-name role per rolesByAccount entry. One app-level stack per account; the deployed CloudFormation name is RolesStack
|
NetworkStack |
hub | The VPN control plane: Headscale on Fargate, one service per site, the key minters, the ACL reconciler. Manual deploy |
ConnectorStack |
each VPC's account | One per target VPC: the tailnet connector, that account's SG-manager and in-VPC resolver. Manual deploy |
PipelineStack |
hub | The GitHub OIDC provider and deploy role CI uses. Deployed manually, once. FNTIO-only |
TestbedStack |
hub | Temporary VPN acceptance test bed. FNTIO-only |
In FNTIO's deployment, pushing main deploys DataStack, CredsStack and WebStack (with WebCertStack as a dependency); the network stacks, PipelineStack and the target-account stacks are hand deploys. Details: Infra: nine CDK stacks. Subsystems inside a stack are constructs in lib/constructs/ (OidcIssuer, VendingApi, AppFunction, AppTable, Monitoring, TailnetConnector, SgManager, TailnetResolver, WebAcl, the web-identity helpers). A construct is a code unit, not a deployment unit, so the stack list above is complete.
Identity is proven cryptographically: the API mints a KMS-signed OIDC web-identity JWT and exchanges it with STS, so no long-lived keys exist anywhere. The target role trusts the issuer URL, never the hub account directly, and its trust condition pins both the audience and a role-scoped subject.
sequenceDiagram
actor U as User
participant A as Web or desktop app
participant C as Cognito
participant P as API Lambda (Express)
participant K as KMS
participant S as STS
participant I as Issuer (S3 + CloudFront)
U->>A: Sign in
A->>C: In-app sign-in (password, passkey, email OTP)
C-->>A: ID token
U->>A: Get credentials for an account and role
A->>P: POST /credentials with Bearer ID token
P->>P: requireAuth verifies the token
P->>P: effectiveFor(user, role target) decides, Roles table resolves the ARN
P->>K: kms:Sign a web-identity JWT, sub = account/role/userId
P->>S: AssumeRoleWithWebIdentity(roleArn, JWT)
S->>I: Fetch discovery document and JWKS (static, cached)
S-->>P: accessKeyId, secretAccessKey, sessionToken
P->>P: Append an activity row (vend or denial)
P-->>A: Credentials (or 403)
A-->>U: Credentials (the desktop writes the resolved profile to ~/.aws/credentials)
POST /accounts/{account}/roles/{role}/console follows the same path and ends in a short-lived console sign-in URL. The Audit table records every vend and denial but is never read to make a decision. The issuer is static: the deploy writes the discovery document and JWKS into a bucket (Custom::OidcIssuerDocuments) and nothing runs when STS fetches them.
Twelve DynamoDB tables in DataStack. Tables reference each other by id; nothing is duplicated.
| Table | Key | Holds |
|---|---|---|
| Accounts | accountNumber |
Registered AWS accounts (name, environment, admin-set profile name) |
| Roles |
accountNumber + roleName
|
The assumable roles; roleArn lives here, the single source of truth |
| Access |
principal + target, GSI byTarget
|
Access model v2: grants exactly as granted (user# or group# to role# or resource#), memberships (member#) and per-role preferences (pref#) |
| Requests |
requestId, GSIs byUser and byStatus
|
Access requests awaiting or holding a decision; byStatus is the admin queue |
| Audit |
eventId, GSIs byUser (subject), byActor and byDay, TTL |
Append-only activity log — every action that changes or uses access, one row each, plus per-user derived rows for group, cascade and bulk changes; never read for an access decision |
| Groups | groupId |
Group identity only; a group's bundle and members are Access rows |
| Resources | resourceId |
The private-network catalog: account, cidr + ports, display dnsName, connection instructions. Also holds the reconciler status sentinel |
| ServiceUsers | clientId |
Registry of machine identities and their rotation state; never decides grants |
| Revocations |
userId + noticeId, TTL |
Access-change notices for the bell — revocations and unasked-for grants; 30-day TTL |
| PluginCatalog | pluginId |
Deployment-written records of the installed plugins: revision, enabled flag, bound accounts, declared permissions, tombstoned or not; read by plugin discovery, the plugin authorizer and pluginAccess.ts, never user grants. Always present, feature on or off |
Users live in Cognito, not a table. Absence of an Access row is default-deny. Column-level detail: Data model: twelve tables; the decision rules are in Access Model.
One Express app, reachable through the portal's CloudFront distribution under /api/* and directly on API Gateway. The contract is packages/infra-client/openapi.yaml (OpenAPI 3.1, ships in the package): 76 paths, 98 operations. A drift test walks the mounted routes and fails when a route is missing from the spec or documented but gone; request and response shapes are maintained by hand. The Postman collection is generated from the spec.
- Authentication: every route except
GET /healthandGET /.well-known/infra-clienttakesAuthorization: Bearer <token>, either a Cognito ID token (humans; admin routes need theadminsgroup claim) or aclient_credentialsaccess token with theapi/invokescope (service users, who are all app admins). - User routes (36 operations): Health; Access (what I may assume, vend, console URL, expiry notices); Requests (raise and list my own, acknowledge decisions); Preferences (profile name, role label, auto-vend star, network, notifications); Network (sites, device key, dev shares and their directory); Resources (what I can reach); Notifications (access changes); Plugins (which plugin pages I may open).
- Admin routes (62 operations): setup and branding; accounts and roles, and their display order; grants, including bulk; users (directory, invites and sign-up links, cascades, MFA reset); service users (create, rotate, retire); groups and members; the request queue (approve, deny); the resource catalog and resource grants; network topology, dev shares and sync; plugins (catalog, per-plugin grants); the activity log and the access report.
- Conventions: JSON errors
{ "message" }, ISO-8601 UTC timestamps, no server-side paging (lists are returned whole and windowed client-side), duration presets from 1 hour to 30 days for temporary access.
Route contract: openapi.yaml, drift-tested against the mounted routes. Consumer view: HTTP API.
-
packages/infra-client/lib/: the stacks (data-stack.ts,creds-stack.ts,web-stack.ts,web-cert-stack.ts,network-stack.ts,connector-stack.ts,target-account-stack.ts),access-portal.ts(addAccessPortal),access-portal-hub.ts(AccessPortalHub),project-config.ts(ProjectConfig),network-validation.ts, andconstructs/. -
packages/infra-client/lambdacode/:api/(app.ts,auth.ts,routes/,services/,__tests__/: thin routers over framework-agnostic services, one file per resource);network/(acl-reconciler.ts,keyminter.ts,sg-manager.ts,resolver.ts, andnaming.ts, the single home of every by-name contract);issuer/(the document publisher);monitoring/(the issuer canary);reapproval/;firstadmin/;headscale-apikey/;plugins/(the shared plugin authorizer and the catalog-record custom resource);federation/(the pre-sign-up trigger that links a federated sign-in to its invite). -
frontend/: the Angular app.desktop/: the Electron shell.infra/: FNTIO's deployment and runbooks.samples/: consumer apps.
Layout rationale: Code layout.
Everything a consuming CDK app needs is exported from the package root; deep imports into dist/ are not part of the contract. The main exports: the ProjectConfig and SiteConfig types; addAccessPortal(scope, props) for the hub stacks; AccessPortalHub.fromAttributes() for cross-account stacks (issuer URL, control URLs, connector key minter and reconciler principal, all derived by name); resolveSites(); TargetAccountStack with the InfraClientRoles constants (InfraReadOnly, InfraPowerUser, InfraFullAdmin); createIssuerProvider and webIdentityPrincipal for hand-built roles; ConnectorStack with TailnetConnector, SgManager and TailnetResolver; the individual hub stacks; WebAcl; the by-name helpers. Constructs take CDK interface objects, never bare ARNs; ready-made stacks are the data boundary. addAccessPortal also accepts webAssetPath to serve a different build of this product's frontend.
Full export table: Public API. Design rules: Public construct API. Custom bundle: Bring your own web build.
Thin HTTP routers over framework-agnostic services — one file per resource, not
per endpoint. New route = add routes/<x>.ts + services/<x>Service.ts.
-
api/app.ts— Express setup, request logging,/health, mounts routers, clean JSON 404/error handlers. Exportshandler = serverless(app)and runsapp.listen(3000)underrequire.main === modulefor local dev. -
api/auth.ts—requireAuth(verify Cognito ID token, setreq.userId+req.groups) andrequireAdmin. -
api/routes/—accounts,credentials,requests,preferences,network,resources,notifications,plugins,admin. -
api/services/—accountsService(user-scoped reads),credentialsService(vend),adminService(account/role catalog reads + writes),grantsService(assign/revoke/list grants),usersService(directory list + Cognito user admin: create/invite, update email + admins group, delete with grant cascade),requestsService(raise/list access requests, the requestable catalog, and approve →grantsService.assignRole/ deny),auditService(append/read the activity log; the actor comes fromactorContext, bound per request),groupsService(role/resource bundles + membership as Access rows;access.tscomputes effective access,accessNotices.tsthe loss diff → notices),reapprovalService(the daily standing-grant sweep — raise reapproval requests / auto-revoke past grace),resourcesService+resourceGrantsService(the network catalog and its grants),sharesService(dev shares),networkStatusService(sites, topology, sync),preferencesService,revocationsService(the bell's notices),serviceUsersService,accessReportService, and the plugin side (pluginCatalog,pluginAccess,pluginGrantsService,pluginDiscoveryService); token checks intokenVerifier(shared with the plugin authorizer); shared error types inhttpErrors. -
api/__tests__/— Jest, one suite per source file (mocked AWS + supertest). -
reapproval/handler.ts— the scheduled (daily) Lambda entry point that callsreapprovalService.sweepReapprovals(); no HTTP surface, separate from the Express app. -
issuer/publish.ts— theCustom::OidcIssuerDocumentshandler: at deploy time it reads every signing key's public key from KMS and writes the OIDC discovery document, the JWKS and a root page into the issuer bucket, which CloudFront serves on the stable custom domain (issuer.portal.example.com; host, zone and zone id come from theissuerblock ofconfig/project.ts— nothing is hardcoded). Nothing runs when STS fetches them. Key rotation: the JWKS publishes every key generation inissuer.keyVersions, so tokens signed by old and new keys verify while both are in flight. The publishedissis always the fixed config value, never derived from a request. (Until 2026-09-08 this was a Lambda behind an API Gateway HTTP API — see "Issuer on S3 + CloudFront".) -
monitoring/issuer-canary.ts— once a minute (EventBridge, in the Monitoring construct) it fetches the public OIDC discovery document exactly the way STS does — full public DNS + TLS + HTTP — then follows itsjwks_uriand requires the active signing key (EXPECT_KID) in the JWKS. Any failure mode that would break vending (deleted Route 53 record, broken cert, missing or stale objects, garbage response) makes the function throw; the alarm on its Errors metric emails the ops topic. No output on success — errors are the signal.
-
DataStack(lib/data-stack.ts) — the twelve tables above. -
CredsStack(lib/creds-stack.ts) — account A: Cognito (+adminsgroup), anOidcIssuerconstruct (KMS RSA signing key(s) + the discovery document and JWKS as static S3 objects behind a CloudFront distribution on a stable custom domain — us-east-1 ACM cert from WebCertStack + Route 53 alias, soissnever drifts (host, zone and zone id come from theissuerblock ofconfig/project.ts— nothing is hardcoded increds-stack.ts)), aVendingApiconstruct (the Express Lambda — Node 22; read/write on every table above (read-only on PluginCatalog),kms:Sign, Cognito user admin (ListUsers/ListUsersInGroup+AdminCreateUser/AdminUpdateUserAttributes/AdminDeleteUser/AdminAddUserToGroup/AdminRemoveUserFromGroup) scoped to this pool's ARN (the admin Users page), nosts:AssumeRole), and aLambdaRestApiproxy that also serves a public, unauthenticatedGET /.well-known/infra-clientdiscovery doc (project name + Cognito ids + issuer) the desktop app reads to self-configure. Receives the tables fromDataStackvia props. The pool is on the Essentials feature plan with choice-based sign-in — the first-auth factors (password, passkey/ WebAuthn, email OTP) come fromPROJECT.loginMethodsinconfig/project.ts, so a deployment re-picks methods without stack-code changes. CredsStack also provisions aReapprovalSweeperLambda on a daily EventBridge schedule — it raises a reapproval request into the admin queue for standing (long-term, direct) grants past their 12-month mark and auto-revokes any left un-reapproved past the grace window. Hardening 2026-07-27: vend API stage throttle (apiThrottle, 25 rps / 50 burst then, 100 / 200 by default since the per-token WAF rule took over the leaked-token job); every Lambda gets 3-month log retention via the sharedAppFunctionconstruct. -
TargetAccountStack(lib/target-account-stack.ts) — a target account (B): an IAM OIDC provider trusting account A's issuer- the assumable roles (one fixed-name
iam.RoleperPROJECT.rolesByAccountentry inconfig/project.ts, its trust built bywebIdentityPrincipal— see "Public construct API" below). One app-level stack per configured account —Roles-<account>— all sharing the deployed CloudFormation nameRolesStack(each lives in a different account, so the names never meet).
- the assumable roles (one fixed-name
-
WebStack(lib/web-stack.ts) — account A: the Angular web frontend (Epic 2) — private S3 bucket + CloudFront (Origin Access Control), SPA deep-link rewrite via a CloudFront Function,BucketDeploymentwith a/*cache invalidation. Always synthesized — synth throws "Web assets not found" whenfrontend/distis missing, sonpm run buildinfrontend/comes before ANY cdk command, even an API-only deploy or a barecdk bootstrap. OutputsWebUrl/DistributionDomain. Also owns the SPA's Cognito app client (USER_AUTH+preventUserExistenceErrors; sign-in is the app's own/loginpage since 2026-08-11) and the Cognito custom auth domain. The Managed Login branding (managed-login-branding.json) is vestigial: the hosted pages no longer serve sign-in, and the login page's skin flows from thebrandingconfig block like the rest of the app. -
WebCertStack(lib/web-cert-stack.ts) — account A, us-east-1: what CloudFront only accepts from that region — the issuer's certificate (always), the web + auth-domain certificate (whenwebis set) and the CloudFront WAF web ACL (when WAF is on, the default — see "Security posture"). Never deployed alone; rides along as a CredsStack- WebStack dependency, so it exists on every deployment.
-
PipelineStack(lib/pipeline-stack.ts) — account A: the GitHub OIDC provider +GithubDeployRolethat CI deploys with (see CI/CD below). Deployed manually, once — the pipeline can't create the role it logs in with. OutputsDeployRoleArn. -
NetworkStack(lib/network-stack.ts) — Epic 4 Headscale control plane; deployed manually/on-demand. -
TestbedStack(lib/testbed-stack.ts) — Epic 4 acceptance test bed, temporary. Verify from a tailnet-connected laptop:curl http://<nginx task private IP>/→ nginx welcome page;psql -h <DbEndpoint output> -U postgres testdb(password inDbSecretArn). Aurora endpoints resolve publicly to the private IP, so no split-DNS is needed. -
ConnectorStack(lib/connector-stack.ts) — one per target VPC; deployed manually. Also carries that account's SG-manager Lambda (see "Per-resource firewall automation").
Subsystems inside a stack live as constructs in
lib/constructs/ — OidcIssuer, VendingApi,
the web-identity.ts helpers, plus AppFunction, AppTable, Monitoring,
WebAcl, TailnetConnector, SgManager and TailnetResolver (FNTIO's
GithubDeployRole lives in infra/lib/constructs/, outside the package). A construct is a code-organization unit, not a deployment
unit: everything in it still deploys as part of its stack, so the stack list
above is complete. The Cognito user pool and the LambdaRestApi deliberately
stay at stack level — WebStack plugs into both, and keeping them out of any
construct keeps their CloudFormation identities (and the cross-stack exports)
stable when the internals are refactored.
The surface a consuming CDK developer sees once this ships as packages (see Releasing). Runnable consumer-voice examples live in ../samples/; design decisions recorded in the packaging doc's "Construct API decisions" section. The rules:
-
Constructs take CDK interface objects (
IVpc,IFunction,IPrincipal,IManagedPolicy) — never bare ARNs/ids. Consumers with only a string use CDK's ownfromXxx()escape hatches. Ready-made stacks are the data boundary: their props may be plain values (vpcId, account ids), since stack props exist before any scope does. -
Quick + flexible path per feature. Target account:
TargetAccountStackfed by theInfraClientRolesconstants (plain-dataTargetRoleSpecs — spreadable, tweakable), orcreateIssuerProvider+webIdentityPrincipalon any hand-builtiam.Role(the oldWebIdentityRolewrapper is gone; a principal factory keeps all ofiam.Role's flexibility). Connector VPC:ConnectorStack, orTailnetConnector+SgManagerin an existing stack. -
Cross-account identity goes through
AccessPortalHub(lib/access-portal-hub.ts): built viafromAttributes({account, region, ...}), it derives every well-known name/ARN of the hub's contract (connector minters, reconciler role, issuer URL, control URLs) from lambdacode/network/naming.ts — now the single home of ALL by-name contract functions. Consumers never assemble an ARN, and site selection stays "which minter may this account invoke" (SITES.md security trap #2). -
Opinionated only where the security model requires it: trust conditions
(
aud+ role-scopedsubpin), role name == the name given towebIdentityPrincipal(the sub pin names it; CDK-generated names can't match), theconnector-<account>hostname contract, the well-known resource names, and theInfraClientRolesrole names (InfraReadOnly,InfraPowerUser,InfraFullAdmin—Infra-prefixed to avoid colliding with AWS's own roles, frozen once any customer deploys them). -
createIssuerProviderreturns a provider whose issuer host is a literal string: IAM condition keys are JSON keys and cannot hold CFN tokens, which the stock L2's token-derived issuer would be.webIdentityPrincipalfails loud at synth if handed a token-issuer provider. -
TailnetConnectornow requiresminter: lambda.IFunction(cross-account:hub.connectorKeyMinter(scope, site)); theminterFunctionArnstring twin and the legacyauthKeySecretjoin path are gone.SgManagertakestrustedInvoker?: iam.IPrincipalinstead of an ARN string.
Verified 2026-08-25 against the live dev deployment: synth templates are
byte-identical to pre-refactor for every stack except ConnectorStack, where
the minter-invoke statement now also lists the :* qualified-versions ARN
(CDK grantInvoke semantics; equivalent grant — applies on the next manual
Epic 4 deploy).
Trust is one-directional: the target role trusts the issuer URL, never account
A directly. Adding target accounts = redeploying RolesStack there; account A's
code never changes.
Bundling: Lambdas are prebundled by
scripts/bundle-lambdas.mjs(esbuild, run bypretest,prepackandcdk.json) intoassets/<name>/index.js. The API keepsexpress,serverless-httpandaws-jwt-verifyexternal and installs them intoassets/api/vendor_modules, whichAppFunctionrenames back tonode_modulesat synth (npm stripsnode_modulesfrom tarballs).
- The site bucket is a by-name contract:
<resourcePrefix>-web-<account>(webBucketName()in web-stack.ts). CredsStack's API Lambda derives the same name — no cross-stack reference, since CredsStack deploys first. One-time migration on the first deploy after this feature: naming the bucket REPLACES the old auto-named one (assets re-upload in the same deploy; the old bucket auto-deletes). Expect a brief cutover blip. -
/branding.jsonhas its own CloudFront behavior with caching disabled — saves show on the next page load, no invalidation. The deploy's bucket sync excludes it so a redeploy can't prune the saved theme. - The Lambda's grant is Get/PutObject on the
branding.jsonkey plus prefix-scoped ListBucket — without ListBucket, S3 reports the not-yet-written overlay as AccessDenied instead of NoSuchKey, and every save/skip 502s (bit us 2026-08-14). - On a stack that predates this feature the route answers 501 until CredsStack + WebStack are redeployed.
Source: wiki/ in FNTIO/aws-infrastructure-client, mirrored by the Wiki workflow. Edit the files there; changes made on this site are overwritten by the next sync.
Start here
Use
How it works
Operate
Contribute