UNPKG

@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
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; }