@fntio/infra-client
Version:
Self-hosted AWS access portal: credential vending, target-account trust, and grant-driven private networking as CDK stacks and constructs.
168 lines (167 loc) • 9.46 kB
TypeScript
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import type { ResolvedDevShares } from "./network-validation";
import type { ResolvedAccountDimensions } from "./dimensions-validation";
import type { DashboardLayoutMode } from "./dashboard-layout";
import * as acm from "aws-cdk-lib/aws-certificatemanager";
import * as apigw from "aws-cdk-lib/aws-apigateway";
import { WafLimits } from "./constructs/web-acl";
import * as cognito from "aws-cdk-lib/aws-cognito";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as sns from "aws-cdk-lib/aws-sns";
import { EmailConfig } from "./data-stack";
import type { ResolvedPersonalAccessTokens } from "./personal-access-tokens";
import type { RoleSessionNamePolicy } from "./role-session-name";
import { PluginApi } from "./plugins/plugin-api";
import type { ResolvedPlugins } from "./plugins/registration";
import { ApiThrottle } from "./api-throttle";
import { type FederatedProvider, type ResolvedFederation } from "./federation";
/** `alertEmail` as the list it stands for: trimmed, de-duplicated, every entry a real address.
* Throws at synth — a placeholder would leave every alarm pointed at nothing. */
export declare function resolveAlertEmails(alertEmail: string | readonly string[]): string[];
/** Sign-in methods offered on the login page's chooser (first-auth factors). */
export interface LoginMethods {
/** Always enabled — Cognito requires it; `false` fails at synth. */
readonly password?: boolean;
/** WebAuthn: Touch ID / Face ID / Windows Hello / security keys. */
readonly passkey?: boolean;
/** Passwordless one-time code sent by email. */
readonly emailOtp?: boolean;
/** TOTP second factor for PASSWORD sign-ins; omit = off. Passkey and MFA
* coexist on the pool, not on one account: Cognito offers a user who
* enrolled an authenticator the password alone (passkey and email code
* return when it is turned off). Scripted sign-ins must enroll before
* "required". REQUIRED (either value) when password is the only first
* factor — Security Hub Cognito.5 — so the choice is in the config. */
readonly mfa?: "optional" | "required";
/** Cognito threat protection in full-function mode (Security Hub Cognito.4):
* blocks password sign-ins with known-leaked passwords (not the SRP flow
* scripts may use — SRP never sends the password) and steps risky sign-ins
* up to MFA when the user enrolled, so `mfa` must be set. PLUS feature
* plan (~$0.02/MAU, no free tier); re-test every sign-in flow after
* turning it on, and expect to remove the risk configuration by hand if a
* later plan downgrade is refused. */
readonly threatProtection?: boolean;
/** Sign in with the customer's own identity provider (OIDC), one entry per provider; local
* methods stay available underneath. Types + rules: federation.ts. */
readonly federation?: readonly FederatedProvider[];
}
export interface CredsStackProps extends cdk.StackProps {
/** `loginMethods.federation`, validated (resolveFederation): adds the mapped claims as pool
* attributes and the pre-sign-up trigger that links federated sign-ins to invited users. */
readonly federation?: ResolvedFederation;
/** Passkey relying-party id (the apex web domain). Omit = Cognito prefix domain. */
readonly passkeyDomain?: string;
/** App origin for the invite email's set-password link. Omitted, the
* invite falls back to a plain-text temp password. */
readonly appUrl?: string;
/** The data-layer tables, owned by DataStack so data outlives this stack. */
readonly accountsTable: dynamodb.ITable;
readonly rolesTable: dynamodb.ITable;
readonly requestsTable: dynamodb.ITable;
readonly auditTable: dynamodb.ITable;
/** TTL every activity row is written with (resolveAuditRetentionDays). Default 400 days. */
readonly auditRetentionDays?: number;
readonly groupsTable: dynamodb.ITable;
readonly resourcesTable: dynamodb.ITable;
readonly accessTable: dynamodb.ITable;
/** Revoked-access notices for the activity bell (informational only). */
readonly revocationsTable: dynamodb.ITable;
/** Service-user (M2M app client) registry. */
readonly serviceUsersTable: dynamodb.ITable;
/** Personal access tokens (always passed; only accepted while `personalAccessTokens` is enabled). */
readonly tokensTable: dynamodb.ITable;
/** Enabled `personalAccessTokens` (resolved); absent = no token is accepted and creation answers 501. */
readonly personalAccessTokens?: ResolvedPersonalAccessTokens;
/** Session naming policy for vended roles (role-session-name.ts). Omit = userId. */
readonly roleSessionName?: RoleSessionNamePolicy;
readonly loginMethods: LoginMethods;
/** Shown in invite emails + the discovery endpoint. No default on purpose. */
readonly projectName: string;
/** SET-ONCE prefix — must match the network stacks' (by-name minter invoke). */
readonly resourcePrefix: string;
/** DataStack's log bucket for the issuer bucket + distribution (S3.9, CloudFront.5). */
readonly accessLogsBucket?: s3.IBucket;
/** Per-site control planes — enables /network. The FIRST site doubles as
* the single `controlUrl` older desktop shells pin. */
readonly networkSites?: ReadonlyArray<{
readonly id: string;
readonly displayName: string;
readonly controlUrl: string;
readonly accounts: readonly string[];
/** Admin-only — the user-facing /network route strips both. */
readonly splitDns?: Record<string, readonly string[]>;
readonly connectorVpcs?: Record<string, ReadonlyArray<{
readonly vpcId: string;
readonly routes: readonly string[];
readonly region?: string;
readonly name?: string;
}>>;
}>;
/** Enabled `network.devShares` (resolved); the API gets it as env, absent = share routes answer 501. */
readonly devShares?: ResolvedDevShares;
/** Enabled `accountDimensions` (resolved); the API reads dims off names at registration. Absent = never. */
readonly accountDimensions?: ResolvedAccountDimensions;
/** Deployment-wide dashboard layout (resolved `dashboard.layout`); the API gets it as DASHBOARD_LAYOUT. Absent = auto. */
readonly dashboardLayout?: DashboardLayoutMode;
/** The stable issuer host — every target account's trust is pinned to
* `https://<domainName>`; it must never change once RolesStack is deployed. */
readonly issuer: {
readonly hostedZoneId: string;
readonly zoneName: string;
readonly domainName: string;
/** Key generations that exist / which one signs (`signerVersion`). */
readonly keyVersions: number[];
readonly signerVersion: number;
/** Covers `domainName`, from WebCertStack (us-east-1) — CloudFront takes
* certificates from no other region. */
readonly certificate: acm.ICertificate;
/** CloudFront-scope web ACL for the issuer distribution (Security Hub
* CloudFront.6) — WebCertStack's. Omit = no WAF. */
readonly webAclArn?: string;
};
/** One address or a list — see ProjectConfig.alertEmail. */
readonly alertEmail: string | readonly string[];
/** prod: the pool + signing keys RETAIN on teardown — a destroyed pool
* takes every user, passkey, and TOTP enrollment with it. */
readonly prod?: boolean;
/** Cognito → SES sender; the domain identity itself lives in DataStack. */
readonly email?: EmailConfig;
/** Advisory list for the setup checklist; the Accounts catalog stays the
* source of truth. */
readonly configAccounts?: ReadonlyArray<{
readonly accountNumber: string;
readonly roles: readonly string[];
}>;
/** Deploy-managed first admin — see ProjectConfig.firstAdmin. */
readonly firstAdmin?: FirstAdminConfig;
/** Customer plugins, on: registrations + the catalog table they read. Absent = feature off. */
readonly plugins?: CredsStackPlugins;
/** Regional web ACL on the API stage (Security Hub APIGateway.4): the
* managed baseline + the per-token rate limit. Omit = no WAF. */
readonly waf?: WafLimits;
/** Stage throttle (api-throttle.ts). Omit = the defaults. */
readonly apiThrottle?: ApiThrottle;
}
export interface CredsStackPlugins extends ResolvedPlugins {
readonly catalogTable: dynamodb.ITable;
readonly assetsBucket: s3.IBucket;
}
export interface FirstAdminConfig {
readonly email: string;
/** Bump to re-send an unclaimed invite on the next deploy. */
readonly resend?: number;
}
export declare class CredsStack extends cdk.Stack {
/** Fronted by WebStack's CloudFront /api/* behavior (same-origin, no CORS). */
readonly api: apigw.LambdaRestApi;
/** Plugin routes + the shared authorizer; present only when plugins are on. */
readonly pluginApi?: PluginApi;
/** Other stacks hook their alarms here. */
readonly alertTopic: sns.ITopic;
/** WebStack attaches the SPA client + domain here — their callback URLs
* need the CloudFront domain (avoids a circular stack ref). */
readonly userPool: cognito.UserPool;
constructor(scope: Construct, id: string, props: CredsStackProps);
}