@fntio/infra-client
Version:
Self-hosted AWS access portal: credential vending, target-account trust, and grant-driven private networking as CDK stacks and constructs.
182 lines (181 loc) • 11.9 kB
TypeScript
import { FirstAdminConfig, LoginMethods } from "./creds-stack";
import { EmailConfig } from "./data-stack";
import { WebBranding, WebDomains } from "./web-stack";
import { TargetRoleSpec } from "./constructs/web-identity";
import { WafConfig } from "./constructs/web-acl";
import { ApiThrottleConfig } from "./api-throttle";
import { AuditConfig } from "./audit-log";
import { PersonalAccessTokensConfig } from "./personal-access-tokens";
import type { RoleSessionNamePolicy } from "./role-session-name";
import { DashboardConfig } from "./dashboard-layout";
/** All per-project configuration for one deployment. */
export interface ProjectConfig {
readonly projectName: string;
/** The hub account + region. Explicit: nothing may depend on which
* credentials run the synth (that ambiguity has faked a CIDR collision). */
readonly env: {
readonly account: string;
readonly region: string;
};
/** true = production hardening: tables (+ PITR, deletion protection), the user pool and the issuer signing keys
* RETAIN on teardown; every hub stack gets termination protection and the VPN load balancer deletion
* protection — a teardown disables both first (runbook "Tear down"). */
readonly prod: boolean;
/** Ops alert recipient(s), one address or a list, each with its own SNS subscription. AWS emails every address
* a confirmation on first deploy — click it or that address gets nothing. The first one is the default
* `email.dmarcReportEmail`. */
readonly alertEmail: string | readonly string[];
/** SET ONCE before the first deploy — every cross-account by-name contract
* derives from it; renaming breaks them all. ≤15 chars. Default "infra-client". */
readonly resourcePrefix?: string;
/** `https://<domainName>` is baked into every target account's trust —
* NEVER change it once deployed; host drift breaks vending everywhere. */
readonly issuer: {
readonly hostedZoneId: string;
readonly zoneName: string;
readonly domainName: string;
/** All listed versions publish in the JWKS; `signerVersion` signs. Omit
* both on day one. Rotation: wiki Runbooks, "Signing-key rotation". */
readonly keyVersions?: number[];
readonly signerVersion?: number;
};
readonly loginMethods: LoginMethods;
/** First admin, created (idempotently, never deleted) by the deploy —
* behavior + failure modes: wiki Runbooks, "First admin". */
readonly firstAdmin?: FirstAdminConfig;
/** Cognito email via SES from this domain (DKIM/SPF/DMARC). Omit = the
* built-in sender (~50/day, spam-prone). Runbook: "Email deliverability". */
readonly email?: EmailConfig;
/** App on `domainName`, sign-in on `authDomainName` — must be a child of
* domainName (Cognito needs the parent to resolve). Runbook: "Custom web domain". */
readonly web?: WebDomains;
/** WAF on CloudFront + the API — ON by default (~$26/month). Turning it
* off later leaves an orphan to delete by hand. Runbook: "Security posture". */
readonly waf?: WafConfig;
/** API Gateway stage throttle on the vending API — the deployment-wide requests-per-second ceiling
* across every caller (a per-token ceiling is `waf.perTokenRateLimit`). Omit = 100 rps, burst 200;
* size for everyone's page loads at once. Wiki: Security Posture. */
readonly apiThrottle?: ApiThrottleConfig;
/** Whether CredsStack sets the ACCOUNT-WIDE API Gateway CloudWatch Logs role (`AWS::ApiGateway::Account`)
* the vending API's stage logging needs. Default true (since 0.1.3, whatever the consumer's
* `@aws-cdk/aws-apigateway:disableCloudWatchRole` flag says). False only when another stack owns that
* role: the deploy then fails with "CloudWatch Logs role ARN must be set in account settings" until it
* is set. Switching a live deployment to false leaves the setting and the old role in place (CDK retains
* both). Wiki: Configuration Reference. */
readonly apiCloudWatchRole?: boolean;
/** The activity log (Activity page): retention of every recorded action. Omit = 400 days.
* Wiki: Admin Guide, "Activity". */
readonly audit?: AuditConfig;
/** Customer plugins: independently built UIs + Lambda routes registered from this CDK app. Off or absent =
* no plugin runtime is created and every plugin grant row stays dormant. Registrations passed to
* `addAccessPortal` while this is off fail at synth. Package README "Plugins". */
readonly plugins?: PluginsConfig;
/** Account dimensions — tenant / project / stage read off each account's name at registration
* (`<tenant>-<project>-<stage>`), filterable on every account list and the group editor. Omit = no
* dimensions anywhere, which is what every deployment had before. Wiki: Admin Guide, "Dimensions". */
readonly accountDimensions?: AccountDimensionsConfig;
/** Dashboard layout for every user: `auto` (the sections once a user holds an account that is off the Main
* section, the plain list until then), `sections` or `plain`. Omit = `auto`. Wiki: Admin Guide, "Dashboard layout". */
readonly dashboard?: DashboardConfig;
/** Personal access tokens: each user creates scoped, revocable tokens (api / aws / network / shares) for
* scripts, CI jobs and command-line tools that act as them. Omit or `enabled: false` = no token is accepted
* and the UI hides the feature. Wiki: Personal Access Tokens. */
readonly personalAccessTokens?: PersonalAccessTokensConfig;
/** How a vended role session is named — what the target account's console and CloudTrail show as the
* federated user. `userId` (default) = `creds-<Cognito sub>`; `email` = the caller's email (a token's
* owner's, a service user's registry name). Wiki: Configuration Reference, "roleSessionName". */
readonly roleSessionName?: RoleSessionNamePolicy;
/** Web app look — logo + colors (project name comes from `projectName`). */
readonly branding: Omit<WebBranding, "projectName">;
/** MUST match the DynamoDB Roles catalog — roles live cross-account, so
* CDK can't verify them at synth. */
readonly rolesByAccount: Record<string, TargetRoleSpec[]>;
/** Per-site Headscale control planes; omit to skip NetworkStack. A site =
* ONE routing domain; only manual step: deleting a removed site's secret. */
readonly network?: {
readonly hostedZoneId: string;
readonly zoneName: string;
/** Sites live at `<site>.<subdomain>.<zoneName>` behind ONE wildcard
* cert + DNS record — adding a site changes neither. */
readonly subdomain: string;
/** Keyed by site id — IMMUTABLE once anything enrolls (it is the login
* hostname of every device and connector). */
readonly sites: Record<string, SiteConfig>;
/** CloudWatch Container Insights on the control-plane cluster (Security
* Hub ECS.12): per-metric cost, a few dollars a month. Default: `prod`. */
readonly containerInsights?: boolean;
/** Run the control servers from a copy of the Headscale image in the hub's own registry, made at deploy, so a
* task restart never depends on the public registry. Toggling restarts each control server once; needs
* `cdk-ecr-deployment` installed in the deployment project. Connector stacks take the same prop. Default false. */
readonly mirrorImages?: boolean;
/** Dev shares: a user shares one local port on their laptop with named users/groups on
* the same site for a bounded time (desktop app runs `tailscale serve`). Off unless
* `enabled`. Runbook: the wiki's Private Network page, "Dev shares". */
readonly devShares?: DevSharesConfig;
};
}
/** `plugins` — validated at synth (lib/plugins/registration.ts resolvePlugins). */
export interface PluginsConfig {
readonly enabled: boolean;
/** How often a signed-in portal re-reads plugin discovery, in seconds (15–300). Default 60. */
readonly discoveryRefreshSeconds?: number;
}
/** What a stage value means to the UI — the role card's silhouette (prod / staging / dev / sandbox). */
export type StageKind = "prod" | "staging" | "dev" | "sandbox";
/** `accountDimensions`, validated at synth (dimensions-validation.ts). Fixed rule: first hyphen-separated segment =
* tenant, last = stage, the rest (may contain hyphens) = project; no hyphen = no dimensions. Stored on the catalog
* row at registration, edited by an admin afterwards (a rename never re-derives them); they filter lists, never decide access. */
export interface AccountDimensionsConfig {
readonly enabled: boolean;
/** What the UI calls each dimension (1–30 characters). Default "Tenant" / "Project" / "Stage". */
readonly labels?: {
readonly tenant?: string;
readonly project?: string;
readonly stage?: string;
};
/** Stage value (as it appears in names, lower-case letters/digits) → silhouette, on top of the built-in
* map (prod/live → prod, staging/test/qa/uat → staging, dev → dev, sandbox → sandbox). */
readonly stages?: Readonly<Record<string, StageKind>>;
}
/** `network.devShares` — validated at synth (network-validation.ts resolveDevShares). */
export interface DevSharesConfig {
readonly enabled: boolean;
/** Longest share a user may create, in hours (1–72). Default 8. */
readonly maxDurationHours?: number;
/** Whether a share may target a group (every member reaches it). Default true. */
readonly allowGroupTargets?: boolean;
/** Most live shares one user may hold at once (1–200). Default 10. */
readonly maxActiveSharesPerOwner?: number;
}
/** One VPC joined via ConnectorStack. */
export interface ConnectorVpcConfig {
readonly vpcId: string;
/** CIDRs to advertise — usually just the VPC's CIDR. */
readonly routes: readonly string[];
/** Only when the VPC is outside the hub's region. */
readonly region?: string;
/** Tells this VPC from the account's others: letters and digits, letter-first, at most 10; unique per account,
* at most one entry per account unnamed. Suffixes the connector hostname (`connector-<account>-<name>`) and the
* SG-manager/resolver function names — set once; renaming a deployed VPC re-enrolls its connector under a new node name. */
readonly name?: string;
}
export interface SiteConfig {
/** Editable any time; the site id stays the permanent machine slug. */
readonly displayName?: string;
/** An account belongs to EXACTLY ONE site; membership always derives from
* accountNumber, never stored on resource rows. */
readonly accounts: readonly string[];
/** May invoke THIS site's connector minter (machine keys only — never the
* device minter). A role ARN is least-privilege; a bare id grants the account. */
readonly connectorAccounts?: readonly string[];
/** Private domain → that VPC's resolver IPs (CIDR base + 2). Per-site:
* overlapping VPCs collide on resolver IPs too. */
readonly splitDns?: Record<string, readonly string[]>;
/** VPCs joined via ConnectorStack, keyed by account id (must appear in `accounts`); drives the deploy and the
* per-site CIDR overlap check. Several VPCs per account take a list, every entry but one carrying a `name`. `region`
* only for a VPC outside the hub's region: ConnectorStack deploys there, reached from the hub through a relay. */
readonly connectorVpcs?: Record<string, ConnectorVpcConfig | readonly ConnectorVpcConfig[]>;
/** Override (100–989) only if two site ids hash-collide (synth tells you).
* Never renumber a deployed rule — CloudFormation fails with PriorityInUse. */
readonly albPriority?: number;
}