@fntio/infra-client 0.0.0-stage → 0.5.0

package/dist/lib/constructs/vending-api.js

@@ -0,0 +1,203 @@
+"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.VendingApi = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+const app_function_1 = require("./app-function");
+const runtime_1 = require("../plugins/runtime");
+/** Lambda caps TOTAL env at 4 KB — bounded so a huge rolesByAccount can
+ *  never fail the deploy (the checklist only shows the first few anyway). */
+function boundedConfigAccounts(accounts) {
+    const kept = [];
+    for (const a of accounts) {
+        kept.push({ accountNumber: a.accountNumber, roles: a.roles.slice(0, 5) });
+        if (JSON.stringify(kept).length > 2500) {
+            kept.pop();
+            break;
+        }
+    }
+    return JSON.stringify(kept);
+}
+/** The Express vending app (lambdacode/api) in Lambda. Express owns routing
+ *  AND auth, so no authorizer is needed at the gateway. */
+class VendingApi extends constructs_1.Construct {
+    /** The Express app's Lambda — front it with API Gateway. */
+    handler;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const { accountsTable, rolesTable, requestsTable, auditTable, groupsTable, resourcesTable, accessTable, revocationsTable, serviceUsersTable, } = props;
+        // One environment for the API and the report job: the job runs the API's own services on the same bundle.
+        const environment = {
+            ACCOUNTS_TABLE_NAME: accountsTable.tableName,
+            ROLES_TABLE_NAME: rolesTable.tableName,
+            REQUESTS_TABLE_NAME: requestsTable.tableName,
+            AUDIT_TABLE_NAME: auditTable.tableName,
+            AUDIT_RETENTION_DAYS: String(props.auditRetentionDays),
+            GROUPS_TABLE_NAME: groupsTable.tableName,
+            RESOURCES_TABLE_NAME: resourcesTable.tableName,
+            ACCESS_TABLE_NAME: accessTable.tableName,
+            REVOCATIONS_TABLE_NAME: revocationsTable.tableName,
+            SERVICE_USERS_TABLE_NAME: serviceUsersTable.tableName,
+            ...(props.plugins
+                ? (0, runtime_1.pluginRuntimeEnv)({ catalogTable: props.plugins.catalogTable, accountsTable }, props.plugins.discoveryRefreshSeconds)
+                : {}),
+            KMS_KEY_ID: props.signingKey.keyId,
+            ISSUER_URL: props.issuerUrl,
+            AUDIENCE: "sts.amazonaws.com",
+            // auth.ts accepts ID tokens from ANY app client of this pool.
+            USER_POOL_ID: props.userPool.userPoolId,
+            USER_POOL_CLIENT_ID: props.userPoolClientId,
+            PROJECT_NAME: props.projectName,
+            ...(props.appUrl ? { APP_URL: props.appUrl } : {}),
+            WEB_BUCKET_NAME: props.webBucketName,
+            EMAIL_CONFIGURED: props.emailConfigured ? "1" : "0",
+            EMAIL_FROM: props.emailFrom ?? "",
+            ...(props.configAccounts?.length
+                ? { CONFIG_ACCOUNTS: boundedConfigAccounts(props.configAccounts) }
+                : {}),
+            NODE_ENV: "production",
+            // Absent → /network answers 501. NETWORK_CONTROL_URL = first site's
+            // URL, for shipped desktop shells that only know one control plane.
+            ...(props.network
+                ? {
+                    NETWORK_SITES: JSON.stringify(props.network.sites),
+                    NETWORK_CONTROL_URL: props.network.sites[0].controlUrl,
+                    NETWORK_KEYMINTER_FN_NAME: props.network.keyMinterFnName,
+                    NETWORK_RECONCILER_FN_NAME: props.network.reconcilerFnName,
+                    ...(props.network.devShares
+                        ? { DEV_SHARES: JSON.stringify(props.network.devShares) }
+                        : {}),
+                }
+                : {}),
+            REPORTS_BUCKET: props.reportsBucket.bucketName,
+            ...(props.accountDimensions ? { ACCOUNT_DIMENSIONS: JSON.stringify(props.accountDimensions) } : {}),
+        };
+        // The access report as a background job (lambdacode/api/services/reportJobs.ts): the same bundle with a
+        // 15-minute budget, invoked asynchronously by the API, writing to the private reports bucket.
+        // Fixed name, invoked BY NAME: a grant by reference would put the function's ARN in the shared role's
+        // policy while the function waits on that same policy — a CloudFormation cycle.
+        new app_function_1.AppFunction(this, "ReportJob", {
+            functionName: props.reportJobFunctionName,
+            description: "The portal's access-report job: builds the CSV the API hands out by link.",
+            asset: "api",
+            handler: "reportJob",
+            role: props.handlerRole,
+            timeout: cdk.Duration.minutes(15),
+            memorySize: 1024,
+            environment,
+        });
+        this.handler = new app_function_1.AppFunction(this, "Handler", {
+            description: "The portal API: access management, requests and credential vending.",
+            asset: "api", // bundled WITH real express node_modules — see the bundler
+            handler: "handler",
+            role: props.handlerRole,
+            timeout: cdk.Duration.seconds(10),
+            // CPU scales with memory: at Lambda's 128 MB default the Express + SDK cold start and the KMS→STS vend
+            // path were CPU-bound (throttle alarms at normal usage); 1024 MB is usually cost-neutral as duration drops.
+            memorySize: 1024,
+            environment: { ...environment, REPORT_JOB_FUNCTION: props.reportJobFunctionName },
+        });
+        this.handler.addToRolePolicy(new iam.PolicyStatement({
+            actions: ["lambda:InvokeFunction"],
+            resources: [
+                cdk.Stack.of(this).formatArn({
+                    service: "lambda",
+                    resource: "function",
+                    resourceName: props.reportJobFunctionName,
+                    arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+                }),
+            ],
+        }));
+        props.reportsBucket.grantReadWrite(this.handler);
+        // Deliberately no sts:AssumeRole — AssumeRoleWithWebIdentity needs no
+        // permission on the caller; the target role's trust policy authorizes it.
+        accountsTable.grantReadWriteData(this.handler);
+        rolesTable.grantReadWriteData(this.handler);
+        requestsTable.grantReadWriteData(this.handler);
+        auditTable.grantReadWriteData(this.handler);
+        groupsTable.grantReadWriteData(this.handler);
+        resourcesTable.grantReadWriteData(this.handler);
+        accessTable.grantReadWriteData(this.handler);
+        revocationsTable.grantReadWriteData(this.handler);
+        serviceUsersTable.grantReadWriteData(this.handler);
+        props.plugins?.catalogTable.grantReadData(this.handler);
+        props.signingKey.grant(this.handler, "kms:Sign");
+        // Private network: device-minter invoke by NAME, not reference, so
+        // CredsStack deploys whether or not NetworkStack exists yet.
+        if (props.network) {
+            this.handler.addToRolePolicy(new iam.PolicyStatement({
+                actions: ["lambda:InvokeFunction"],
+                resources: [props.network.keyMinterFnName, props.network.reconcilerFnName].map((name) => cdk.Stack.of(this).formatArn({
+                    service: "lambda",
+                    resource: "function",
+                    resourceName: name,
+                    arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+                })),
+            }));
+        }
+        // Cognito user admin for the /admin/users routes — scoped to THIS pool's
+        // ARN, and every route sits behind requireAuth + requireAdmin.
+        this.handler.addToRolePolicy(new iam.PolicyStatement({
+            actions: [
+                "cognito-idp:ListUsers",
+                "cognito-idp:ListUsersInGroup",
+                // Consistent sub → identity lookups (sign-up link, resend, MFA reset, email change).
+                "cognito-idp:AdminGetUser",
+                "cognito-idp:AdminCreateUser",
+                // A fresh temporary password behind "Copy sign-up link" (never a permanent one).
+                "cognito-idp:AdminSetUserPassword",
+                "cognito-idp:AdminUpdateUserAttributes",
+                "cognito-idp:AdminDeleteUser",
+                // Ends a deleted/demoted user's sessions at once (see auth.ts requireAdmin).
+                "cognito-idp:AdminUserGlobalSignOut",
+                "cognito-idp:AdminAddUserToGroup",
+                "cognito-idp:AdminRemoveUserFromGroup",
+                // Invite-time link of the email to each federated provider, discovered from the pool.
+                "cognito-idp:AdminLinkProviderForUser",
+                "cognito-idp:AdminDisableProviderForUser",
+                "cognito-idp:ListIdentityProviders",
+                // Runtime-created M2M clients can only ever get the `api/invoke`
+                // scope — never a human sign-in.
+                "cognito-idp:CreateUserPoolClient",
+                "cognito-idp:DeleteUserPoolClient",
+                "cognito-idp:DescribeUserPoolClient",
+            ],
+            resources: [props.userPool.userPoolArn],
+        }));
+    }
+}
+exports.VendingApi = VendingApi;

package/dist/lib/constructs/web-acl.d.ts

@@ -0,0 +1,61 @@
+import { Construct } from "constructs";
+/** AWS WAF in front of the web app (CloudFront) and the API (API Gateway
+ *  stage). ON by default — Security Hub CSPM fails APIGateway.4 and
+ *  CloudFront.6 without it. Rules, cost, opt-out: the Security
+ *  Posture wiki page. */
+export interface WafConfig {
+    /** false = no web ACLs at all. Default true. */
+    readonly enabled?: boolean;
+    /** `/api/*` requests per client IP per 5 minutes before CloudFront answers
+     *  429. One office NAT is one IP — size for the office. Default 5000. */
+    readonly rateLimit?: number;
+    /** API requests per bearer token per 5 minutes before the API's WAF answers
+     *  429. Per TOKEN, not per user: a browser session keeps one token for up to
+     *  an hour (each refresh starts a new bucket) and a service user can mint a
+     *  fresh token any time — a ceiling on a runaway or leaked token, sized
+     *  above the product's own bursts (import CLI, bulk UI actions, the e2e
+     *  suite). Default 2000. */
+    readonly perTokenRateLimit?: number;
+}
+/** The resolved limits — undefined when WAF is off. */
+export interface WafLimits {
+    readonly rateLimit: number;
+    readonly perTokenRateLimit: number;
+}
+export declare function resolveWaf(config?: WafConfig): WafLimits | undefined;
+export interface WebAclProps {
+    /** CLOUDFRONT-scope ACLs only exist in us-east-1 (WAF rule). */
+    readonly scope: "REGIONAL" | "CLOUDFRONT";
+    /** Web ACL, metric and log-group name — unique per account + region + scope. */
+    readonly name: string;
+    /** Per-source-IP limit on requests under `pathPrefix`, per 5 minutes. Only
+     *  where WAF sees the viewer IP, i.e. on CloudFront — behind it the only
+     *  key is the client-writable X-Forwarded-For. */
+    readonly rateLimit?: {
+        readonly limit: number;
+        readonly pathPrefix: string;
+    };
+    /** Per-bearer-token limit (the `authorization` header value is the key) on
+     *  requests under `pathPrefix` (omit = every request), per 5 minutes. Sound
+     *  behind CloudFront too: tokens are signed, so nobody lands in another
+     *  caller's bucket; junk tokens get their own and die 401 at the API. */
+    readonly tokenRateLimit?: {
+        readonly limit: number;
+        readonly pathPrefix?: string;
+    };
+    /** Every managed rule runs in COUNT: the ACL logs what it would have
+     *  blocked and never blocks. For the issuer distribution — STS is its
+     *  only client, and a false positive there fails every vend silently. */
+    readonly observeOnly?: boolean;
+}
+/** CommonRuleSet rules that only COUNT here: the API is JSON with free
+ *  text, URLs, bulk-import batches and SVG data-URI logos, all shape-checked
+ *  server-side, and M2M clients may send no User-Agent. */
+export declare const COMMON_RULES_COUNT_ONLY: string[];
+/** One WAFv2 web ACL: optional per-IP and per-token rate limits + the AWS managed baseline
+ *  (IP reputation, known bad inputs, common rule set), logging blocks and
+ *  counts to CloudWatch with credentials redacted. */
+export declare class WebAcl extends Construct {
+    readonly arn: string;
+    constructor(scope: Construct, id: string, props: WebAclProps);
+}

package/dist/lib/constructs/web-acl.js

@@ -0,0 +1,213 @@
+"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.WebAcl = exports.COMMON_RULES_COUNT_ONLY = void 0;
+exports.resolveWaf = resolveWaf;
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const logs = __importStar(require("aws-cdk-lib/aws-logs"));
+const wafv2 = __importStar(require("aws-cdk-lib/aws-wafv2"));
+function resolveWaf(config) {
+    if (config?.enabled === false)
+        return undefined;
+    const bounded = (field, value, unit) => {
+        if (!Number.isInteger(value) || value < 10 || value > 2_000_000_000) {
+            throw new Error(`waf.${field} (${value}) must be an integer from 10 to 2000000000 — ${unit}.`);
+        }
+        return value;
+    };
+    return {
+        rateLimit: bounded("rateLimit", config?.rateLimit ?? 5000, "/api/* requests per client IP per 5 minutes"),
+        perTokenRateLimit: bounded("perTokenRateLimit", config?.perTokenRateLimit ?? 2000, "API requests per bearer token per 5 minutes"),
+    };
+}
+/** CommonRuleSet rules that only COUNT here: the API is JSON with free
+ *  text, URLs, bulk-import batches and SVG data-URI logos, all shape-checked
+ *  server-side, and M2M clients may send no User-Agent. */
+exports.COMMON_RULES_COUNT_ONLY = [
+    "NoUserAgent_HEADER",
+    "SizeRestrictions_BODY",
+    "GenericRFI_BODY",
+    "GenericLFI_BODY",
+    "CrossSiteScripting_BODY",
+];
+/** One WAFv2 web ACL: optional per-IP and per-token rate limits + the AWS managed baseline
+ *  (IP reputation, known bad inputs, common rule set), logging blocks and
+ *  counts to CloudWatch with credentials redacted. */
+class WebAcl extends constructs_1.Construct {
+    arn;
+    constructor(scope, id, props) {
+        super(scope, id);
+        // Sampled requests are kept unredacted for 3 hours; the redacted log
+        // below is the only capture.
+        const visibility = (metricName) => ({
+            cloudWatchMetricsEnabled: true,
+            sampledRequestsEnabled: false,
+            metricName,
+        });
+        const managed = (name, countOnly) => ({
+            name,
+            overrideAction: props.observeOnly ? { count: {} } : { none: {} },
+            visibilityConfig: visibility(name),
+            statement: {
+                managedRuleGroupStatement: {
+                    vendorName: "AWS",
+                    name,
+                    ruleActionOverrides: props.observeOnly
+                        ? undefined
+                        : countOnly?.map((rule) => ({
+                            name: rule,
+                            actionToUse: { count: {} },
+                        })),
+                },
+            },
+        });
+        const block429 = {
+            block: {
+                customResponse: {
+                    responseCode: 429,
+                    responseHeaders: [{ name: "Retry-After", value: "60" }],
+                },
+            },
+        };
+        const underPath = (pathPrefix) => pathPrefix === undefined
+            ? undefined
+            : {
+                byteMatchStatement: {
+                    fieldToMatch: { uriPath: {} },
+                    positionalConstraint: "STARTS_WITH",
+                    searchString: pathPrefix,
+                    textTransformations: [{ priority: 0, type: "NONE" }],
+                },
+            };
+        const rateRules = [];
+        if (props.rateLimit) {
+            rateRules.push({
+                name: "RateLimit",
+                action: block429,
+                visibilityConfig: visibility("RateLimit"),
+                statement: {
+                    rateBasedStatement: {
+                        limit: props.rateLimit.limit,
+                        evaluationWindowSec: 300,
+                        aggregateKeyType: "IP",
+                        scopeDownStatement: underPath(props.rateLimit.pathPrefix),
+                    },
+                },
+            });
+        }
+        if (props.tokenRateLimit) {
+            rateRules.push({
+                name: "TokenRateLimit",
+                action: block429,
+                visibilityConfig: visibility("TokenRateLimit"),
+                statement: {
+                    rateBasedStatement: {
+                        limit: props.tokenRateLimit.limit,
+                        evaluationWindowSec: 300,
+                        aggregateKeyType: "CUSTOM_KEYS",
+                        customKeys: [
+                            {
+                                header: {
+                                    name: "authorization",
+                                    textTransformations: [{ priority: 0, type: "NONE" }],
+                                },
+                            },
+                        ],
+                        scopeDownStatement: underPath(props.tokenRateLimit.pathPrefix),
+                    },
+                },
+            });
+        }
+        const acl = new wafv2.CfnWebACL(this, "Acl", {
+            name: props.name,
+            scope: props.scope,
+            defaultAction: { allow: {} },
+            visibilityConfig: visibility(props.name),
+            // Evaluated in array order.
+            rules: [
+                ...rateRules,
+                managed("AWSManagedRulesAmazonIpReputationList"),
+                managed("AWSManagedRulesKnownBadInputsRuleSet"),
+                managed("AWSManagedRulesCommonRuleSet", exports.COMMON_RULES_COUNT_ONLY),
+            ].map((rule, priority) => ({ ...rule, priority })),
+        });
+        if (props.scope === "CLOUDFRONT") {
+            // The distribution detaches only after this stack deploys, and deleting
+            // an attached ACL fails the update — orphan it; cleanup is in the README.
+            acl.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);
+        }
+        this.arn = acl.attrArn;
+        // WAF only delivers to groups named aws-waf-logs-*; a retained named
+        // group collides on re-create, so this one goes with the stack.
+        const logGroup = new logs.LogGroup(this, "Logs", {
+            logGroupName: `aws-waf-logs-${props.name}`,
+            retention: logs.RetentionDays.THREE_MONTHS,
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        });
+        new wafv2.CfnLoggingConfiguration(this, "Logging", {
+            resourceArn: acl.attrArn,
+            // WAF rejects the log group's own ARN (it ends in ":*").
+            logDestinationConfigs: [
+                cdk.Stack.of(this).formatArn({
+                    service: "logs",
+                    resource: "log-group",
+                    resourceName: logGroup.logGroupName,
+                    arnFormat: cdk.ArnFormat.COLON_RESOURCE_NAME,
+                }),
+            ],
+            // Blocked requests carry bearer tokens.
+            redactedFields: [
+                { singleHeader: { Name: "authorization" } },
+                { singleHeader: { Name: "cookie" } },
+            ],
+            // Allowed traffic would be a per-request ingestion bill for no signal.
+            loggingFilter: {
+                DefaultBehavior: "DROP",
+                Filters: [
+                    {
+                        Behavior: "KEEP",
+                        Requirement: "MEETS_ANY",
+                        Conditions: [
+                            { ActionCondition: { Action: "BLOCK" } },
+                            { ActionCondition: { Action: "COUNT" } },
+                        ],
+                    },
+                ],
+            },
+        });
+    }
+}
+exports.WebAcl = WebAcl;

package/dist/lib/constructs/web-identity.d.ts

@@ -0,0 +1,49 @@
+import * as cdk from "aws-cdk-lib";
+import { Construct } from "constructs";
+import * as iam from "aws-cdk-lib/aws-iam";
+/** One assumable target role for the quick path; the flexible path builds
+ *  any `iam.Role` with `webIdentityPrincipal()` as its `assumedBy` instead. */
+export interface TargetRoleSpec {
+    /** Must match the hub's Roles catalog; pinned into the trust policy's sub
+     *  condition — immutable once anything vends against it. */
+    readonly roleName: string;
+    /** What the vended credentials may do — any IManagedPolicy works. */
+    readonly managedPolicies: readonly iam.IManagedPolicy[];
+    readonly description?: string;
+    /** IAM cap on vended sessions (1h–12h; default 12h = STS max, so the
+     *  admin-set per-role session length in the app is the effective limit). */
+    readonly maxSessionDuration?: cdk.Duration;
+}
+/** Prepackaged common roles. Each roleName is a frozen contract baked into
+ *  deployed trust policies — entries may be added, never renamed. */
+export declare const InfraClientRoles: {
+    /** Account-wide read-only (AWS ReadOnlyAccess). */
+    READ_ONLY: {
+        roleName: string;
+        managedPolicies: cdk.aws_iam.IManagedPolicy[];
+        description: string;
+    };
+    /** Full access except IAM/account management (AWS PowerUserAccess). */
+    POWER_USER: {
+        roleName: string;
+        managedPolicies: cdk.aws_iam.IManagedPolicy[];
+        description: string;
+    };
+    /** Full administrative access (AWS AdministratorAccess). */
+    FULL_ADMIN: {
+        roleName: string;
+        managedPolicies: cdk.aws_iam.IManagedPolicy[];
+        description: string;
+    };
+};
+/** The issuer URL as IAM condition keys name it: host only, no scheme or trailing slash. */
+export declare const issuerHost: (issuerUrl: string) => string;
+/** The account's one OIDC provider for the hub's issuer. Reports the issuer
+ *  HOST as a literal — JSON policy condition keys cannot hold CFN tokens. */
+export declare function createIssuerProvider(scope: Construct, id: string, issuerUrl: string): iam.IOpenIdConnectProvider;
+/** Pinned to audience + role-scoped sub — a token only assumes the role it
+ *  was minted for. The trusting role MUST use exactly this fixed roleName. */
+export declare function webIdentityPrincipal(provider: iam.IOpenIdConnectProvider, roleName: string): iam.WebIdentityPrincipal;
+/** The same pin from a provider ARN and a literal issuer host — for a template whose provider is a native
+ *  `AWS::IAM::OIDCProvider` (no construct to ask) and whose account is only known at deploy time. */
+export declare function webIdentityPrincipalFor(providerArn: string, issuer: string, roleName: string, account?: string): iam.WebIdentityPrincipal;

package/dist/lib/constructs/web-identity.js

@@ -0,0 +1,116 @@
+"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.issuerHost = exports.InfraClientRoles = void 0;
+exports.createIssuerProvider = createIssuerProvider;
+exports.webIdentityPrincipal = webIdentityPrincipal;
+exports.webIdentityPrincipalFor = webIdentityPrincipalFor;
+const cdk = __importStar(require("aws-cdk-lib"));
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+/** Prepackaged common roles. Each roleName is a frozen contract baked into
+ *  deployed trust policies — entries may be added, never renamed. */
+exports.InfraClientRoles = {
+    /** Account-wide read-only (AWS ReadOnlyAccess). */
+    READ_ONLY: {
+        roleName: "InfraReadOnly",
+        managedPolicies: [
+            iam.ManagedPolicy.fromAwsManagedPolicyName("ReadOnlyAccess"),
+        ],
+        description: "Read-only access, assumed via the credential-vending issuer.",
+    },
+    /** Full access except IAM/account management (AWS PowerUserAccess). */
+    POWER_USER: {
+        roleName: "InfraPowerUser",
+        managedPolicies: [
+            iam.ManagedPolicy.fromAwsManagedPolicyName("PowerUserAccess"),
+        ],
+        description: "Power-user access (no IAM), assumed via the credential-vending issuer.",
+    },
+    /** Full administrative access (AWS AdministratorAccess). */
+    FULL_ADMIN: {
+        roleName: "InfraFullAdmin",
+        managedPolicies: [
+            iam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess"),
+        ],
+        description: "Administrator access, assumed via the credential-vending issuer.",
+    },
+};
+/** The issuer URL as IAM condition keys name it: host only, no scheme or trailing slash. */
+const issuerHost = (issuerUrl) => issuerUrl.replace(/^https:\/\//, "").replace(/\/$/, "");
+exports.issuerHost = issuerHost;
+/** The account's one OIDC provider for the hub's issuer. Reports the issuer
+ *  HOST as a literal — JSON policy condition keys cannot hold CFN tokens. */
+function createIssuerProvider(scope, id, issuerUrl) {
+    return new IssuerProvider(scope, id, issuerUrl);
+}
+class IssuerProvider extends iam.OpenIdConnectProvider {
+    literalIssuer;
+    constructor(scope, id, issuerUrl) {
+        super(scope, id, {
+            url: issuerUrl,
+            clientIds: ["sts.amazonaws.com"], // == AUDIENCE in the minted token
+        });
+        this.literalIssuer = (0, exports.issuerHost)(issuerUrl);
+    }
+    get openIdConnectProviderIssuer() {
+        return this.literalIssuer;
+    }
+}
+/** Pinned to audience + role-scoped sub — a token only assumes the role it
+ *  was minted for. The trusting role MUST use exactly this fixed roleName. */
+function webIdentityPrincipal(provider, roleName) {
+    const issuer = provider.openIdConnectProviderIssuer;
+    if (cdk.Token.isUnresolved(issuer)) {
+        throw new Error("webIdentityPrincipal: the provider's issuer is a CloudFormation " +
+            "token, which cannot form IAM condition keys. Pass the provider " +
+            "returned by createIssuerProvider(), or import one via " +
+            "iam.OpenIdConnectProvider.fromOpenIdConnectProviderArn().");
+    }
+    return webIdentityPrincipalFor(provider.openIdConnectProviderArn, issuer, roleName, cdk.Stack.of(provider).account);
+}
+/** The same pin from a provider ARN and a literal issuer host — for a template whose provider is a native
+ *  `AWS::IAM::OIDCProvider` (no construct to ask) and whose account is only known at deploy time. */
+function webIdentityPrincipalFor(providerArn, issuer, roleName, account = cdk.Aws.ACCOUNT_ID) {
+    return new iam.WebIdentityPrincipal(providerArn, {
+        StringEquals: {
+            [`${issuer}:aud`]: "sts.amazonaws.com",
+        },
+        StringLike: {
+            // DEPLOY ORDER: CredsStack (new sub format) must be live before this
+            // condition lands anywhere — see the Access Model wiki page ("Sub-pinning").
+            [`${issuer}:sub`]: `${account}/${roleName}/*`,
+        },
+    });
+}