@fntio/infra-client
Version:
Self-hosted AWS access portal: credential vending, target-account trust, and grant-driven private networking as CDK stacks and constructs.
186 lines (185 loc) • 11.8 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 all 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 gets 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;
/** 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 being up. Turning it on (or off)
* restarts each control server once; needs `cdk-ecr-deployment` installed in the deployment project.
* Connector stacks take the same switch as a 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 resolveAccountDimensions). The naming
* rule is fixed: first hyphen-separated segment = tenant, last = stage, the rest (which may contain hyphens)
* = project; `acme-prod` has no project; a name without a hyphen gets no dimensions ("unclassified"). Values
* are stored on the catalog row when the account is registered and are edited by an admin afterwards —
* renaming an account never re-derives them. They filter lists; they 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, and at most one entry per account goes unnamed.
* Becomes the connector's hostname suffix (`connector-<account>-<name>`) and the
* suffix of its SG-manager and 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.
* One VPC per account is the common case; several take a list, every
* entry but one carrying a `name`. `region` only when a VPC is outside
* the hub's region (omit = hub region): ConnectorStack deploys there, and
* the reconciler reaches that VPC's SG-manager and resolver through a
* relay outside the hub VPC. */
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;
}