@fntio/infra-client 0.0.0-stage → 0.5.0

package/dist/lib/data-stack.js

@@ -0,0 +1,282 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataStack = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const dynamodb = __importStar(require("aws-cdk-lib/aws-dynamodb"));
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+const s3 = __importStar(require("aws-cdk-lib/aws-s3"));
+const route53 = __importStar(require("aws-cdk-lib/aws-route53"));
+const ses = __importStar(require("aws-cdk-lib/aws-ses"));
+const app_table_1 = require("./constructs/app-table");
+/** The DynamoDB tables — separate from CredsStack so durable data outlives
+ *  compute redeploys. */
+class DataStack extends cdk.Stack {
+    accountsTable;
+    rolesTable;
+    requestsTable;
+    auditTable;
+    groupsTable;
+    resourcesTable;
+    /** Access model v2: grants stored exactly as granted — principal → target,
+     *  plus member#/pref# rows; `byTarget` = who holds X. */
+    accessTable;
+    revocationsTable;
+    /** clientId → name + rotation state; grants live in Access under `user#<clientId>`. */
+    serviceUsersTable;
+    /** Plugin catalog (Epic 5): deployment-written records, keyed by pluginId. Always present so enabling or
+     *  disabling the feature never adds or removes a cross-stack export; unused until `plugins.enabled`. */
+    pluginCatalogTable;
+    /** Plugin UIs under immutable `<id>/<version>-<hash>/` prefixes: uploaded by CredsStack's registrations
+     *  (so a record can depend on its upload), served by WebStack's /plugin-assets/* behavior, never touched
+     *  by the site deploy's prune. */
+    pluginAssetsBucket;
+    /** Server-access logs of every hub bucket and the standard logs of both CloudFront distributions
+     *  (Security Hub S3.9, CloudFront.5). ACL-based ownership: that is what CloudFront's standard logging
+     *  and S3 log delivery write with, and it keeps the other stacks free of a cross-stack bucket-policy
+     *  reference back into this one. The one bucket that logs nowhere — AWS says to suppress S3.9 on it. */
+    accessLogsBucket;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const prod = props?.prod ?? false;
+        if (props?.email) {
+            const { hostedZoneId, zoneName, dmarcReportEmail } = props.email;
+            const zone = route53.HostedZone.fromHostedZoneAttributes(this, "EmailZone", {
+                hostedZoneId,
+                zoneName,
+            });
+            // Auto-creates DKIM + MAIL FROM records. SES verifies async (minutes) —
+            // the first CredsStack deploy can race it (README "Email deliverability").
+            new ses.EmailIdentity(this, "EmailIdentity", {
+                identity: ses.Identity.publicHostedZone(zone),
+                mailFromDomain: `mail.${zoneName}`,
+            });
+            // Receivers ignore cross-org DMARC reports without an authorizing TXT
+            // (see warning below); parent/child of the zone approximates same-org.
+            const reportDomain = dmarcReportEmail?.split("@")[1]?.toLowerCase();
+            const zoneLower = zoneName.toLowerCase();
+            const sameOrg = !!reportDomain &&
+                (reportDomain === zoneLower ||
+                    zoneLower.endsWith(`.${reportDomain}`) ||
+                    reportDomain.endsWith(`.${zoneLower}`));
+            if (dmarcReportEmail && !sameOrg) {
+                cdk.Annotations.of(this).addWarningV2("infra-client:dmarc-cross-domain-rua", `DMARC reports for ${zoneName} go to ${dmarcReportEmail} — a ` +
+                    `cross-domain rua needs a "${zoneName}._report._dmarc.<recipient ` +
+                    `domain>" TXT record on the recipient's zone, or receivers drop ` +
+                    `the reports.`);
+            }
+            new route53.TxtRecord(this, "DmarcRecord", {
+                zone,
+                recordName: `_dmarc.${zoneName}`,
+                values: [
+                    `v=DMARC1; p=quarantine;${dmarcReportEmail ? ` rua=mailto:${dmarcReportEmail}` : ""}`,
+                ],
+            });
+        }
+        this.accountsTable = new app_table_1.AppTable(this, "AccountsTable", {
+            partitionKey: {
+                name: "accountNumber",
+                type: dynamodb.AttributeType.STRING,
+            },
+            prod,
+        });
+        // roleArn lives here as an attribute — the single source of truth vending assumes.
+        this.rolesTable = new app_table_1.AppTable(this, "RolesTable", {
+            partitionKey: {
+                name: "accountNumber",
+                type: dynamodb.AttributeType.STRING,
+            },
+            sortKey: { name: "roleName", type: dynamodb.AttributeType.STRING },
+            prod,
+        });
+        this.accessTable = new app_table_1.AppTable(this, "AccessTable", {
+            partitionKey: { name: "principal", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "target", type: dynamodb.AttributeType.STRING },
+            // Only dev-share rows carry `ttl` (expiry + a day); every other row lives until deleted.
+            timeToLiveAttribute: "ttl",
+            prod,
+        });
+        this.accessTable.addGlobalSecondaryIndex({
+            indexName: "byTarget",
+            partitionKey: { name: "target", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "principal", type: dynamodb.AttributeType.STRING },
+        });
+        // A request never confers access — approving one writes an Access row, and
+        // vending reads only Access.
+        this.requestsTable = new app_table_1.AppTable(this, "RequestsTable", {
+            partitionKey: { name: "requestId", type: dynamodb.AttributeType.STRING },
+            prod,
+        });
+        this.requestsTable.addGlobalSecondaryIndex({
+            indexName: "byUser",
+            partitionKey: { name: "userId", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "createdAt", type: dynamodb.AttributeType.STRING },
+        });
+        // All pending requests share one byStatus partition — fine at tens of
+        // rows; shard before volume makes it hot.
+        this.requestsTable.addGlobalSecondaryIndex({
+            indexName: "byStatus",
+            partitionKey: { name: "status", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "createdAt", type: dynamodb.AttributeType.STRING },
+        });
+        // Append-only activity log (services/auditService.ts); never read for an access decision — Access stays
+        // the only gate. TTL bounds retention (default 400 days > the annual review; config `audit.retentionDays`).
+        this.auditTable = new app_table_1.AppTable(this, "AuditTable", {
+            partitionKey: { name: "eventId", type: dynamodb.AttributeType.STRING },
+            timeToLiveAttribute: "expiresAt",
+            prod,
+        });
+        this.auditTable.addGlobalSecondaryIndex({
+            indexName: "byUser",
+            partitionKey: { name: "userId", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "at", type: dynamodb.AttributeType.STRING },
+        });
+        this.auditTable.addGlobalSecondaryIndex({
+            indexName: "byDay",
+            partitionKey: { name: "day", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "at", type: dynamodb.AttributeType.STRING },
+        });
+        // Who did it (byUser = whom it was done to). Sparse: only rows with an actor.
+        this.auditTable.addGlobalSecondaryIndex({
+            indexName: "byActor",
+            partitionKey: { name: "actorId", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "at", type: dynamodb.AttributeType.STRING },
+        });
+        // Group identity only — memberships and grant bundles live in the Access
+        // table; this table never decides access.
+        this.groupsTable = new app_table_1.AppTable(this, "GroupsTable", {
+            partitionKey: { name: "groupId", type: dynamodb.AttributeType.STRING },
+            prod,
+        });
+        // PK is a generated uuid so grants survive renames/re-addressing; `cidr`
+        // is the ACL destination (README "Resource catalog").
+        this.resourcesTable = new app_table_1.AppTable(this, "ResourcesTable", {
+            partitionKey: { name: "resourceId", type: dynamodb.AttributeType.STRING },
+            prod,
+        });
+        // The clientId doubles as the access-table principal (a token's `sub` IS
+        // the client id); this table never decides access.
+        this.serviceUsersTable = new app_table_1.AppTable(this, "ServiceUsersTable", {
+            partitionKey: { name: "clientId", type: dynamodb.AttributeType.STRING },
+            prod,
+        });
+        // A revoke DELETES the grant row, so each revoke path writes a notice
+        // here. Informational only — never read for an access decision.
+        this.revocationsTable = new app_table_1.AppTable(this, "RevocationsTable", {
+            partitionKey: { name: "userId", type: dynamodb.AttributeType.STRING },
+            sortKey: { name: "noticeId", type: dynamodb.AttributeType.STRING },
+            timeToLiveAttribute: "ttl",
+            prod,
+        });
+        new cdk.CfnOutput(this, "AccountsTableName", {
+            value: this.accountsTable.tableName,
+        });
+        new cdk.CfnOutput(this, "RolesTableName", {
+            value: this.rolesTable.tableName,
+        });
+        new cdk.CfnOutput(this, "RequestsTableName", {
+            value: this.requestsTable.tableName,
+        });
+        new cdk.CfnOutput(this, "AuditTableName", {
+            value: this.auditTable.tableName,
+        });
+        new cdk.CfnOutput(this, "GroupsTableName", {
+            value: this.groupsTable.tableName,
+        });
+        new cdk.CfnOutput(this, "ResourcesTableName", {
+            value: this.resourcesTable.tableName,
+        });
+        new cdk.CfnOutput(this, "AccessTableName", {
+            value: this.accessTable.tableName,
+        });
+        new cdk.CfnOutput(this, "RevocationsTableName", {
+            value: this.revocationsTable.tableName,
+        });
+        this.pluginCatalogTable = new app_table_1.AppTable(this, "PluginCatalogTable", {
+            partitionKey: { name: "pluginId", type: dynamodb.AttributeType.STRING },
+            prod,
+        });
+        this.accessLogsBucket = new s3.Bucket(this, "AccessLogsBucket", {
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            enforceSSL: true,
+            encryption: s3.BucketEncryption.S3_MANAGED,
+            objectOwnership: s3.ObjectOwnership.OBJECT_WRITER,
+            accessControl: s3.BucketAccessControl.LOG_DELIVERY_WRITE,
+            lifecycleRules: [
+                { expiration: cdk.Duration.days(90), abortIncompleteMultipartUploadAfter: cdk.Duration.days(7) },
+            ],
+            removalPolicy: prod ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
+            autoDeleteObjects: !prod,
+        });
+        this.pluginAssetsBucket = new s3.Bucket(this, "PluginAssetsBucket", {
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            enforceSSL: true,
+            removalPolicy: cdk.RemovalPolicy.DESTROY, // redeployable build output
+            autoDeleteObjects: true,
+            lifecycleRules: [{ abortIncompleteMultipartUploadAfter: cdk.Duration.days(7) }],
+            serverAccessLogsBucket: this.accessLogsBucket,
+            serverAccessLogsPrefix: "s3/plugin-assets/",
+        });
+        // CloudFront (OAC) is the only reader. The distribution lives in WebStack, which cannot write this policy
+        // without a stack cycle, so the grant names any distribution of this account.
+        this.pluginAssetsBucket.addToResourcePolicy(new iam.PolicyStatement({
+            actions: ["s3:GetObject"],
+            resources: [this.pluginAssetsBucket.arnForObjects("*")],
+            principals: [new iam.ServicePrincipal("cloudfront.amazonaws.com")],
+            conditions: { ArnLike: { "AWS:SourceArn": `arn:${cdk.Aws.PARTITION}:cloudfront::${cdk.Aws.ACCOUNT_ID}:distribution/*` } },
+        }));
+        // The other stacks reference the table and bucket only while plugins are ON. Exporting them explicitly keeps
+        // the exports alive when the feature is switched off, so DataStack (deployed first) never fails with
+        // "export in use by CredsStack/WebStack" on that transition.
+        for (const value of [
+            this.pluginCatalogTable.tableName,
+            this.pluginCatalogTable.tableArn,
+            this.pluginAssetsBucket.bucketName,
+            this.pluginAssetsBucket.bucketArn,
+        ]) {
+            this.exportValue(value);
+        }
+        // Removing a table another stack still imports fails DataStack with "export in use" (DataStack
+        // deploys first): drop the consumers' references in one release and the table in the next (the
+        // 0.1.18 → 0.2.0 removal of the access-model-v1 tables).
+        new cdk.CfnOutput(this, "PluginCatalogTableName", {
+            value: this.pluginCatalogTable.tableName,
+        });
+        new cdk.CfnOutput(this, "ServiceUsersTableName", {
+            value: this.serviceUsersTable.tableName,
+        });
+    }
+}
+exports.DataStack = DataStack;

package/dist/lib/dimensions-validation.d.ts

@@ -0,0 +1,20 @@
+import { AccountDimensionsConfig, StageKind } from "./project-config";
+/** `accountDimensions` as the deploy uses it: the API's env (ACCOUNT_DIMENSIONS) and config.json's `dimensions`. */
+export interface ResolvedAccountDimensions {
+    readonly enabled: boolean;
+    readonly labels: {
+        readonly tenant: string;
+        readonly project: string;
+        readonly stage: string;
+    };
+    /** Stage value (lower-case) → role-card silhouette. */
+    readonly stages: Readonly<Record<string, StageKind>>;
+}
+export declare const DEFAULT_DIMENSION_LABELS: {
+    readonly tenant: "Tenant";
+    readonly project: "Project";
+    readonly stage: "Stage";
+};
+/** What a stage value means when the block lists none: the dashboard's old name heuristic, made explicit. */
+export declare const DEFAULT_STAGE_KINDS: Readonly<Record<string, StageKind>>;
+export declare function resolveAccountDimensions(cfg?: AccountDimensionsConfig): ResolvedAccountDimensions | undefined;

package/dist/lib/dimensions-validation.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STAGE_KINDS = exports.DEFAULT_DIMENSION_LABELS = void 0;
+exports.resolveAccountDimensions = resolveAccountDimensions;
+exports.DEFAULT_DIMENSION_LABELS = { tenant: "Tenant", project: "Project", stage: "Stage" };
+/** What a stage value means when the block lists none: the dashboard's old name heuristic, made explicit. */
+exports.DEFAULT_STAGE_KINDS = {
+    prod: "prod",
+    prd: "prod",
+    production: "prod",
+    live: "prod",
+    staging: "staging",
+    stage: "staging",
+    stg: "staging",
+    preprod: "staging",
+    test: "staging",
+    qa: "staging",
+    uat: "staging",
+    dev: "dev",
+    develop: "dev",
+    development: "dev",
+    eng: "dev",
+    sandbox: "sandbox",
+    sbx: "sandbox",
+};
+const STAGE_KINDS = ["prod", "staging", "dev", "sandbox"];
+function resolveAccountDimensions(cfg) {
+    if (!cfg)
+        return undefined;
+    const labels = { ...exports.DEFAULT_DIMENSION_LABELS };
+    for (const key of ["tenant", "project", "stage"]) {
+        const v = cfg.labels?.[key];
+        if (v === undefined)
+            continue;
+        if (typeof v !== "string" || !v.trim() || v.trim().length > 30) {
+            throw new Error(`accountDimensions.labels.${key} must be 1 to 30 characters (got ${JSON.stringify(v)}).`);
+        }
+        labels[key] = v.trim();
+    }
+    const stages = { ...exports.DEFAULT_STAGE_KINDS };
+    for (const [value, kind] of Object.entries(cfg.stages ?? {})) {
+        if (!/^[a-z0-9]+$/.test(value)) {
+            throw new Error(`accountDimensions.stages key "${value}" must be lower-case letters and digits (a stage as it appears in account names).`);
+        }
+        if (!STAGE_KINDS.includes(kind)) {
+            throw new Error(`accountDimensions.stages.${value} must be one of ${STAGE_KINDS.join(", ")} (got ${JSON.stringify(kind)}).`);
+        }
+        stages[value] = kind;
+    }
+    return { enabled: cfg.enabled === true, labels, stages };
+}

package/dist/lib/federation.d.ts

@@ -0,0 +1,113 @@
+import * as cognito from "aws-cdk-lib/aws-cognito";
+/** `loginMethods.federation` — sign in with an external OIDC provider (Entra, Okta, Ping,
+ *  Keycloak, Google Workspace…), validated at synth (resolveFederation). Runbook: wiki
+ *  Runbooks-Users, "Federated sign-in (SSO)". */
+/** One custom claim copied from the provider's token onto the user (a `custom:<key>` pool
+ *  attribute) and into the portal's own ID token. */
+export interface FederatedClaim {
+    /** The provider's claim name the value comes from (Entra's `oid`, Okta's `employeeNumber`…). */
+    readonly from: string;
+    /** Cap on the stored value, 1–2048 (Cognito's ceiling). Default 256. */
+    readonly maxLen?: number;
+    /** Shown next to the value in the admin directory and activity. Default: the key. */
+    readonly label?: string;
+}
+export interface FederatedProvider {
+    /** Cognito provider name — the `identity_provider` the login page asks for and the prefix of
+     *  auto-created usernames. Letters, digits, `-`; ≤32 chars; unique. Treat as permanent: renaming
+     *  orphans every linked identity. */
+    readonly name: string;
+    /** Sign-in button text. Default: `name`. */
+    readonly label?: string;
+    /** Only `"oidc"` today; `"saml"` fails at synth until it is built. */
+    readonly type: "oidc";
+    /** The provider's issuer, exactly as its discovery document states it (Cognito fetches
+     *  `<issuerUrl>/.well-known/openid-configuration` at deploy). */
+    readonly issuerUrl: string;
+    readonly clientId: string;
+    /** Secrets Manager ARN holding the client secret as a PLAIN string (not JSON), in the
+     *  deployment's region. The value never enters the repo or the template. */
+    readonly clientSecretArn: string;
+    /** Pin a secret version after rotating it — CloudFormation only re-reads the secret when
+     *  the provider resource changes. Omit to read the current version on the next deploy. */
+    readonly clientSecretVersionId?: string;
+    /** OAuth scopes requested from the provider. Default `openid profile email`; `openid` is required. */
+    readonly scopes?: readonly string[];
+    /** Standard Cognito attributes (camelCase, e.g. `givenName`) → provider claim. `email` defaults
+     *  to `"email"` and cannot be dropped: it is the invite-linking key and the user's name. */
+    readonly attributeMapping?: Readonly<Record<string, string>>;
+    /** Custom claims to carry, keyed by the attribute name. PERMANENT for the pool's life: Cognito
+     *  can neither rename nor remove custom attributes (50 max). */
+    readonly claims?: Readonly<Record<string, FederatedClaim>>;
+    /** Extra hosts the provider's sign-in may redirect through (a tenant's own ADFS, `login.live.com`).
+     *  Allowlist semantics: wiki Configuration-Reference, `allowedHosts`. */
+    readonly allowedHosts?: readonly string[];
+}
+export interface ResolvedFederatedClaim {
+    readonly key: string;
+    readonly from: string;
+    readonly maxLen: number;
+    readonly label: string;
+}
+export interface ResolvedFederatedProvider {
+    readonly name: string;
+    readonly label: string;
+    readonly issuerUrl: string;
+    readonly clientId: string;
+    readonly clientSecretArn: string;
+    readonly clientSecretVersionId?: string;
+    readonly scopes: readonly string[];
+    /** CDK attribute-mapping keys → provider claim; `email` always present. */
+    readonly attributeMapping: Readonly<Partial<Record<StandardAttributeKey, string>>> & {
+        readonly email: string;
+    };
+    readonly claims: readonly ResolvedFederatedClaim[];
+    /** Hosts the desktop shell allows in-view for this provider (issuer host first). */
+    readonly hosts: readonly string[];
+}
+export interface ResolvedFederation {
+    readonly providers: readonly ResolvedFederatedProvider[];
+    /** Union of every provider's claim keys — one `custom:<key>` pool attribute each, capped at
+     *  the widest `maxLen` any provider asks for; the label is the first provider's. */
+    readonly claimKeys: readonly ResolvedFederatedClaim[];
+}
+/** The keys CDK's AttributeMapping accepts (minus `custom`, which `claims` drives). Typed against
+ *  CDK so a typo fails tsc, not a deploy. */
+declare const STANDARD_ATTRIBUTE_KEYS: readonly ["address", "birthdate", "email", "familyName", "gender", "givenName", "locale", "middleName", "fullname", "nickname", "phoneNumber", "profilePicture", "preferredUsername", "profilePage", "timezone", "lastUpdateTime", "website"];
+export type StandardAttributeKey = (typeof STANDARD_ATTRIBUTE_KEYS)[number];
+export declare const MAX_CUSTOM_ATTRIBUTES = 50;
+/** Cognito links at most 5 identities to a user; each provider may cost two (the invite-time
+ *  email link plus the trigger's subject link on a mismatch), so two providers is the safe ceiling. */
+export declare const MAX_PROVIDERS = 2;
+export declare const MAX_CLAIM_LEN = 2048;
+/** Validate + default `loginMethods.federation`; `undefined` when absent or empty. Every
+ *  rule here fails a deploy or a sign-in later, silently. */
+export declare function resolveFederation(federation: readonly FederatedProvider[] | undefined, region: string): ResolvedFederation | undefined;
+/** `{{resolve:secretsmanager:…}}` for the provider's client secret — resolved by CloudFormation
+ *  at deploy, so the plaintext is in neither the synthesized template nor the repo. */
+export declare function clientSecretReference(p: ResolvedFederatedProvider): string;
+/** Every standard attribute plus the mapped claims — what a client may read into ID tokens. */
+export declare function readAttributes(claimKeys: readonly ResolvedFederatedClaim[]): cognito.ClientAttributes;
+/** Every standard attribute, plus the mapped claims ONLY for the federation client: Cognito
+ *  writes a mapped attribute through the signing-in client, and that same permission lets a
+ *  user's self-service call set it — so no client a local session can hold gets it. */
+export declare function writeAttributes(claimKeys: readonly ResolvedFederatedClaim[], opts: {
+    claims: boolean;
+}): cognito.ClientAttributes;
+/** CDK AttributeMapping for one provider: the standard keys plus `custom:<key>` for each claim. */
+export declare function providerAttributeMapping(p: ResolvedFederatedProvider): cognito.AttributeMapping;
+/** What config.json carries — public ids only (the frontend's login buttons + labels, the
+ *  desktop shell's navigation allowlist). */
+export declare function federationAppConfig(f: ResolvedFederation, clientId: string): {
+    clientId: string;
+    providers: {
+        name: string;
+        label: string;
+        hosts: string[];
+    }[];
+    claims: {
+        key: string;
+        label: string;
+    }[];
+};
+export {};