@fntio/infra-client 0.0.0-stage → 0.5.0

package/dist/lib/constructs/monitoring.js

@@ -0,0 +1,133 @@
+"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.Monitoring = void 0;
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const cloudwatch = __importStar(require("aws-cdk-lib/aws-cloudwatch"));
+const cwactions = __importStar(require("aws-cdk-lib/aws-cloudwatch-actions"));
+const events = __importStar(require("aws-cdk-lib/aws-events"));
+const targets = __importStar(require("aws-cdk-lib/aws-events-targets"));
+const logs = __importStar(require("aws-cdk-lib/aws-logs"));
+const sns = __importStar(require("aws-cdk-lib/aws-sns"));
+const subs = __importStar(require("aws-cdk-lib/aws-sns-subscriptions"));
+const app_function_1 = require("./app-function");
+const objects_1 = require("../../lambdacode/issuer/objects");
+/** Lambda error/throttle alarms, a DENIED-spike alarm, and an issuer health
+ *  canary — all fanned out through one SNS topic. */
+class Monitoring extends constructs_1.Construct {
+    /** All alarms notify here; add subscriptions to add recipients. */
+    topic;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.topic = new sns.Topic(this, "AlertTopic", {
+            displayName: "Infra ops alerts",
+            enforceSSL: true,
+        });
+        for (const email of props.alertEmails) {
+            this.topic.addSubscription(new subs.EmailSubscription(email));
+        }
+        const notify = new cwactions.SnsAction(this.topic);
+        const fnAlarm = (fn, name, metric, what) => {
+            const alarm = new cloudwatch.Alarm(this, name, {
+                metric,
+                threshold: 1,
+                evaluationPeriods: 1,
+                comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+                treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+                alarmDescription: `${what} on ${fn.functionName} — check its CloudWatch logs.`,
+            });
+            alarm.addAlarmAction(notify);
+            return alarm;
+        };
+        const vendingFn = props.vendingFn;
+        fnAlarm(vendingFn, "VendApiErrors", vendingFn.metricErrors({ period: cdk.Duration.minutes(5) }), "Invocation errors");
+        fnAlarm(vendingFn, "VendApiThrottles", vendingFn.metricThrottles({ period: cdk.Duration.minutes(5) }), "Throttled invocations");
+        // Occasional denials are normal user error; a burst is a token
+        // systematically probing roles it doesn't own.
+        const denied = new logs.MetricFilter(this, "DeniedFilter", {
+            logGroup: props.vendingFn.logGroup,
+            filterPattern: logs.FilterPattern.stringValue("$.msg", "=", "DENIED*"),
+            metricNamespace: "InfraClient",
+            metricName: "VendDenied",
+            metricValue: "1",
+        });
+        const deniedAlarm = new cloudwatch.Alarm(this, "DeniedSpike", {
+            metric: denied.metric({
+                period: cdk.Duration.minutes(15),
+                statistic: "sum",
+            }),
+            threshold: 5,
+            evaluationPeriods: 1,
+            comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+            alarmDescription: "5+ DENIED vend attempts in 15 min — possible probing with a leaked or " +
+                "over-curious token. Check the Audit table / API logs for the userId.",
+        });
+        deniedAlarm.addAlarmAction(notify);
+        // Outside-in canary: the issuer is static objects behind CloudFront, so
+        // only an end-to-end probe (like STS does) sees DNS/cert/serving failures
+        // — and a JWKS missing the active key.
+        const canary = new app_function_1.AppFunction(this, "IssuerCanary", {
+            description: "Health probe: fetches the public credential issuer every minute and checks its signing key.",
+            asset: "issuer-canary",
+            handler: "handler",
+            timeout: cdk.Duration.seconds(10),
+            environment: {
+                CHECK_URL: `${props.issuerUrl.replace(/\/$/, "")}/${objects_1.ISSUER_OBJECTS.discovery}`,
+                EXPECT_KID: props.signingKeyId,
+            },
+        });
+        new events.Rule(this, "CanarySchedule", {
+            description: "Probe the public issuer discovery document every minute.",
+            schedule: events.Schedule.rate(cdk.Duration.minutes(1)),
+            targets: [new targets.LambdaFunction(canary)],
+        });
+        const issuerHealth = new cloudwatch.Alarm(this, "IssuerHealth", {
+            metric: canary.metricErrors({ period: cdk.Duration.minutes(5) }),
+            threshold: 2,
+            evaluationPeriods: 1,
+            comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+            alarmDescription: "The public issuer discovery URL is failing — vending will fail " +
+                "everywhere until this recovers. Check DNS, the certificate, the " +
+                "issuer CloudFront distribution, then the issuer bucket's objects " +
+                "(runbook: wiki Runbooks, \"Issuer on S3 + CloudFront\").",
+        });
+        issuerHealth.addAlarmAction(notify);
+        issuerHealth.addOkAction(notify); // recovery email, since the outage is silent otherwise
+    }
+}
+exports.Monitoring = Monitoring;

package/dist/lib/constructs/oidc-issuer.d.ts

@@ -0,0 +1,44 @@
+import { Construct } from "constructs";
+import * as acm from "aws-cdk-lib/aws-certificatemanager";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as kms from "aws-cdk-lib/aws-kms";
+import * as s3 from "aws-cdk-lib/aws-s3";
+export interface OidcIssuerProps {
+    /** Route 53 zone owning `domainName` — holds the alias. */
+    readonly hostedZoneId: string;
+    readonly zoneName: string;
+    /** The stable issuer host — the issuer IDENTITY. Must never change once
+     *  target accounts trust it; must sit inside `zoneName`. */
+    readonly domainName: string;
+    /** Key generations that EXIST — each is published in the JWKS so STS can
+     *  verify tokens from any of them. Rotation runbook: wiki Runbooks-Issuer. */
+    readonly keyVersions: number[];
+    /** Which version actively signs new tokens. Must appear in `keyVersions`. */
+    readonly signerVersion: number;
+    /** The ONLY principal allowed kms:Sign on the active key — everything
+     *  else, IAM-policy self-grants included, is refused at the key. */
+    readonly signerRole: iam.IRole;
+    /** Covers `domainName`. CloudFront accepts certificates from us-east-1
+     *  only — WebCertStack mints it there. */
+    readonly certificate: acm.ICertificate;
+    /** CloudFront-scope web ACL ARN (us-east-1) for the distribution
+     *  (Security Hub CloudFront.6) — WebCertStack's observe-only one, which
+     *  never blocks STS. Omit = no WAF. */
+    readonly webAclArn?: string;
+    /** Production hardening: the signing keys RETAIN on teardown. */
+    readonly prod?: boolean;
+    /** DataStack's log bucket: the issuer bucket's server-access logs and the distribution's standard logs. */
+    readonly accessLogsBucket?: s3.IBucket;
+}
+/** KMS signing key(s) plus the discovery document + JWKS as static objects:
+ *  a deploy-time custom resource writes them into a private bucket that
+ *  CloudFront serves on the stable custom domain. Nothing runs when STS
+ *  fetches them. The domain IS the issuer identity — recreating the
+ *  construct never changes it. */
+export declare class OidcIssuer extends Construct {
+    /** Signs the vended web-identity tokens. Grant kms:Sign to whoever mints. */
+    readonly signingKey: kms.Key;
+    /** The public issuer URL — the `iss` claim of every minted token. Stable. */
+    readonly url: string;
+    constructor(scope: Construct, id: string, props: OidcIssuerProps);
+}

package/dist/lib/constructs/oidc-issuer.js

@@ -0,0 +1,234 @@
+"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.OidcIssuer = void 0;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const cloudfront = __importStar(require("aws-cdk-lib/aws-cloudfront"));
+const origins = __importStar(require("aws-cdk-lib/aws-cloudfront-origins"));
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+const kms = __importStar(require("aws-cdk-lib/aws-kms"));
+const logs = __importStar(require("aws-cdk-lib/aws-logs"));
+const route53 = __importStar(require("aws-cdk-lib/aws-route53"));
+const targets = __importStar(require("aws-cdk-lib/aws-route53-targets"));
+const s3 = __importStar(require("aws-cdk-lib/aws-s3"));
+const cr = __importStar(require("aws-cdk-lib/custom-resources"));
+const app_function_1 = require("./app-function");
+const pkg_paths_1 = require("../pkg-paths");
+const objects_1 = require("../../lambdacode/issuer/objects");
+/** KMS signing key(s) plus the discovery document + JWKS as static objects:
+ *  a deploy-time custom resource writes them into a private bucket that
+ *  CloudFront serves on the stable custom domain. Nothing runs when STS
+ *  fetches them. The domain IS the issuer identity — recreating the
+ *  construct never changes it. */
+class OidcIssuer extends constructs_1.Construct {
+    /** Signs the vended web-identity tokens. Grant kms:Sign to whoever mints. */
+    signingKey;
+    /** The public issuer URL — the `iss` claim of every minted token. Stable. */
+    url;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.url = `https://${props.domainName}`;
+        // Outside the zone the alias record can't be written.
+        if (props.domainName !== props.zoneName &&
+            !props.domainName.endsWith(`.${props.zoneName}`)) {
+            throw new Error(`issuer.domainName (${props.domainName}) must be issuer.zoneName or ` +
+                `a subdomain of it (${props.zoneName}).`);
+        }
+        if (!props.keyVersions.includes(props.signerVersion)) {
+            throw new Error(`issuer.signerVersion ${props.signerVersion} is not in keyVersions ` +
+                `[${props.keyVersions}] — the active signer's key must be published ` +
+                `in the JWKS or STS will reject every token.`);
+        }
+        if (new Set(props.keyVersions).size !== props.keyVersions.length) {
+            throw new Error(`issuer.keyVersions has duplicates: [${props.keyVersions}]`);
+        }
+        // Explicit role so the key policies below can name it — an implicit
+        // function role would come to life AFTER the keys. Keeps the logical id
+        // of the retired JWKS Lambda's role, so no key policy changes principal.
+        const publisherRole = new iam.Role(this, "JwksRole", {
+            assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
+            managedPolicies: [
+                iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
+            ],
+        });
+        // Replaces the default policy — its IAM delegation lets any principal
+        // grant ITSELF kms:Sign and mint forgeable tokens. Named principals only.
+        const keyPolicy = (allowSign) => new iam.PolicyDocument({
+            statements: [
+                new iam.PolicyStatement({
+                    sid: "KeyAdministration",
+                    principals: [new iam.AccountRootPrincipal()],
+                    actions: [
+                        "kms:Create*",
+                        "kms:Describe*",
+                        "kms:Enable*",
+                        "kms:List*",
+                        "kms:Put*",
+                        "kms:Update*",
+                        "kms:Revoke*",
+                        "kms:Disable*",
+                        "kms:Get*",
+                        "kms:Delete*",
+                        "kms:TagResource",
+                        "kms:UntagResource",
+                        "kms:ScheduleKeyDeletion",
+                        "kms:CancelKeyDeletion",
+                    ],
+                    resources: ["*"],
+                }),
+                new iam.PolicyStatement({
+                    sid: "JwksRead",
+                    principals: [publisherRole],
+                    actions: ["kms:GetPublicKey"],
+                    resources: ["*"],
+                }),
+                ...(allowSign
+                    ? [
+                        new iam.PolicyStatement({
+                            sid: "VendSign",
+                            principals: [props.signerRole],
+                            actions: ["kms:Sign"],
+                            resources: ["*"],
+                        }),
+                    ]
+                    : []),
+            ],
+        });
+        const keysByVersion = new Map();
+        for (const version of props.keyVersions) {
+            // Version 1 keeps the original "SigningKey" logical id so introducing
+            // versioning never replaced the deployed key.
+            const id = version === 1 ? "SigningKey" : `SigningKeyV${version}`;
+            keysByVersion.set(version, new kms.Key(this, id, {
+                keySpec: kms.KeySpec.RSA_2048,
+                keyUsage: kms.KeyUsage.SIGN_VERIFY,
+                // Older generations verify-only: nothing may Sign with them.
+                policy: keyPolicy(version === props.signerVersion),
+                // prod: RETAIN — deleting a signer invalidates every outstanding
+                // vended token at once.
+                removalPolicy: props.prod
+                    ? cdk.RemovalPolicy.RETAIN
+                    : cdk.RemovalPolicy.DESTROY,
+            }));
+        }
+        this.signingKey = keysByVersion.get(props.signerVersion);
+        // Contents are regenerated by every deploy — nothing to retain.
+        const bucket = new s3.Bucket(this, "Bucket", {
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            enforceSSL: true,
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+            autoDeleteObjects: true,
+            lifecycleRules: [{ abortIncompleteMultipartUploadAfter: cdk.Duration.days(7) }],
+            serverAccessLogsBucket: props.accessLogsBucket,
+            serverAccessLogsPrefix: props.accessLogsBucket && "s3/issuer/",
+        });
+        // kms:GetPublicKey comes from the key policies' JwksRead statement alone.
+        const publisher = new app_function_1.AppFunction(this, "Publisher", {
+            description: "Deploy-time helper: publishes the credential issuer's discovery document and public keys.",
+            asset: "issuer-publish",
+            handler: "handler",
+            role: publisherRole,
+            timeout: cdk.Duration.seconds(60),
+        });
+        // Exactly the three objects — no prefix wildcard.
+        publisherRole.addToPrincipalPolicy(new iam.PolicyStatement({
+            actions: ["s3:PutObject"],
+            resources: Object.values(objects_1.ISSUER_OBJECTS).map((key) => bucket.arnForObjects(key)),
+        }));
+        const provider = new cr.Provider(this, "PublishProvider", {
+            onEventHandler: publisher,
+            logGroup: new logs.LogGroup(this, "PublishProviderLogs", {
+                retention: logs.RetentionDays.THREE_MONTHS,
+            }),
+        });
+        const documents = new cdk.CustomResource(this, "Documents", {
+            serviceToken: provider.serviceToken,
+            resourceType: "Custom::OidcIssuerDocuments",
+            properties: {
+                Bucket: bucket.bucketName,
+                // Fixed value, never derived from the request host — the identity
+                // can't drift even if the fronting changes.
+                Issuer: this.url,
+                // ALL generations — tokens signed before a rotation flip stay
+                // verifiable.
+                KeyIds: props.keyVersions.map((v) => keysByVersion.get(v).keyId),
+                // Nothing else ever rewrites the objects, so a publisher change must
+                // be an Update on its own.
+                PublisherHash: crypto
+                    .createHash("sha256")
+                    .update(fs.readFileSync(path.join((0, pkg_paths_1.packageRoot)(), "assets", "issuer-publish", "index.js")))
+                    .digest("hex"),
+            },
+        });
+        const distribution = new cloudfront.Distribution(this, "Distribution", {
+            comment: "OIDC issuer (discovery document + JWKS)",
+            domainNames: [props.domainName],
+            certificate: props.certificate,
+            minimumProtocolVersion: cloudfront.SecurityPolicyProtocol.TLS_V1_2_2021,
+            webAclId: props.webAclArn,
+            defaultRootObject: objects_1.ISSUER_OBJECTS.index,
+            ...(props.accessLogsBucket
+                ? { enableLogging: true, logBucket: props.accessLogsBucket, logFilePrefix: "cloudfront/issuer/", logIncludesCookies: false }
+                : {}),
+            defaultBehavior: {
+                origin: origins.S3BucketOrigin.withOriginAccessControl(bucket),
+                viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.HTTPS_ONLY,
+                allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD,
+                // Honors the objects' Cache-Control (5 minutes).
+                cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
+                responseHeadersPolicy: cloudfront.ResponseHeadersPolicy.SECURITY_HEADERS,
+            },
+        });
+        const zone = route53.HostedZone.fromHostedZoneAttributes(this, "Zone", {
+            hostedZoneId: props.hostedZoneId,
+            zoneName: props.zoneName,
+        });
+        const target = route53.RecordTarget.fromAlias(new targets.CloudFrontTarget(distribution));
+        // "AliasRecord" is the API Gateway alias's logical id — CloudFormation
+        // updates the record in place, and only once the documents exist.
+        for (const [id, Record] of [
+            ["AliasRecord", route53.ARecord],
+            ["AliasRecordV6", route53.AaaaRecord],
+        ]) {
+            new Record(this, id, { zone, recordName: props.domainName, target })
+                .node.addDependency(documents);
+        }
+    }
+}
+exports.OidcIssuer = OidcIssuer;

package/dist/lib/constructs/scratch-tmpfs.d.ts

@@ -0,0 +1,5 @@
+import * as ecs from "aws-cdk-lib/aws-ecs";
+import { Construct } from "constructs";
+/** A per-container tmpfs at /tmp: the one writable path a non-root container on a read-only root
+ *  gets without a task volume (a Fargate task volume is root-owned 0755 whatever the image says). */
+export declare function scratchTmpfs(scope: Construct, id: string, sizeMiB: number): ecs.LinuxParameters;

package/dist/lib/constructs/scratch-tmpfs.js

@@ -0,0 +1,48 @@
+"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.scratchTmpfs = scratchTmpfs;
+const ecs = __importStar(require("aws-cdk-lib/aws-ecs"));
+/** A per-container tmpfs at /tmp: the one writable path a non-root container on a read-only root
+ *  gets without a task volume (a Fargate task volume is root-owned 0755 whatever the image says). */
+function scratchTmpfs(scope, id, sizeMiB) {
+    const lp = new ecs.LinuxParameters(scope, id);
+    lp.addTmpfs({
+        containerPath: "/tmp",
+        size: sizeMiB,
+        mountOptions: [ecs.TmpfsMountOption.NOSUID, ecs.TmpfsMountOption.NODEV, ecs.TmpfsMountOption.NOEXEC],
+    });
+    return lp;
+}

package/dist/lib/constructs/sg-manager.d.ts

@@ -0,0 +1,27 @@
+import { Construct } from "constructs";
+import * as ec2 from "aws-cdk-lib/aws-ec2";
+import * as iam from "aws-cdk-lib/aws-iam";
+import { AppFunction } from "./app-function";
+export interface SgManagerProps {
+    /** The hub's SET-ONCE product prefix (hub.resourcePrefix) — the well-known
+     *  function name and the managed-rule marker derive from it. */
+    readonly resourcePrefix: string;
+    /** Mutating IAM is pinned to this VPC (`ec2:Vpc` condition) — so resources
+     *  in a PEERED VPC can't use SG automation. */
+    readonly vpc: ec2.IVpc;
+    /** The connector's SG in this account — the only source the manager ever
+     *  writes into ingress rules (env, never caller input). */
+    readonly connectorSecurityGroup: ec2.ISecurityGroup;
+    /** The hub's reconciler role (`hub.aclReconcilerPrincipal()`). Omit when
+     *  the reconciler is same-account — identity policy alone suffices. */
+    readonly trustedInvoker?: iam.IPrincipal;
+    /** The connector VPC's name (config `connectorVpcs[].name`) — suffixes the
+     *  function name so an account's second VPC gets its own manager. */
+    readonly name?: string;
+}
+/** Lives in the target account so the reconciler never holds EC2 permissions
+ *  anywhere — it may only ask this fn, which only opens this VPC's groups. */
+export declare class SgManager extends Construct {
+    readonly fn: AppFunction;
+    constructor(scope: Construct, id: string, props: SgManagerProps);
+}

package/dist/lib/constructs/sg-manager.js

@@ -0,0 +1,88 @@
+"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.SgManager = 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 naming_1 = require("../../lambdacode/network/naming");
+/** Lives in the target account so the reconciler never holds EC2 permissions
+ *  anywhere — it may only ask this fn, which only opens this VPC's groups. */
+class SgManager extends constructs_1.Construct {
+    fn;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const stack = cdk.Stack.of(this);
+        this.fn = new app_function_1.AppFunction(this, "Fn", {
+            functionName: (0, naming_1.sgManagerFnName)(props.resourcePrefix, props.name),
+            description: "Opens and closes security-group rules so the VPN connector reaches granted resources in this VPC.",
+            asset: "sg-manager",
+            handler: "handler",
+            timeout: cdk.Duration.seconds(30),
+            environment: {
+                CONNECTOR_SG_ID: props.connectorSecurityGroup.securityGroupId,
+                RESOURCE_PREFIX: props.resourcePrefix, // managed-rule marker derivation
+                VPC_ID: props.vpc.vpcId, // groups elsewhere are answered `other-vpc`, not touched
+            },
+        });
+        // Describe has no resource-level scoping; the mutating pair is pinned to
+        // the connector's VPC so the blast radius is "this VPC", not "the account".
+        this.fn.addToRolePolicy(new iam.PolicyStatement({
+            actions: ["ec2:DescribeSecurityGroups"],
+            resources: ["*"],
+        }));
+        this.fn.addToRolePolicy(new iam.PolicyStatement({
+            actions: [
+                "ec2:AuthorizeSecurityGroupIngress",
+                "ec2:RevokeSecurityGroupIngress",
+            ],
+            resources: [
+                `arn:aws:ec2:${stack.region}:${stack.account}:security-group/*`,
+            ],
+            conditions: { StringEquals: { "ec2:Vpc": props.vpc.vpcArn } },
+        }));
+        if (props.trustedInvoker) {
+            // Lambda validates the principal exists — NetworkStack deploys first,
+            // and redeploy here if the reconciler role is ever recreated.
+            this.fn.addPermission("ReconcilerInvoke", {
+                principal: props.trustedInvoker,
+                action: "lambda:InvokeFunction",
+            });
+        }
+        new cdk.CfnOutput(this, "SgManagerArn", { value: this.fn.functionArn });
+    }
+}
+exports.SgManager = SgManager;

package/dist/lib/constructs/tailnet-connector.d.ts

@@ -0,0 +1,29 @@
+import { Construct } from "constructs";
+import * as ec2 from "aws-cdk-lib/aws-ec2";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+export interface TailnetConnectorProps {
+    /** The VPC whose private resources this connector makes reachable. */
+    readonly vpc: ec2.IVpc;
+    /** Headscale control plane, e.g. https://headscale.access.example.com */
+    readonly controlUrl: string;
+    /** CIDRs advertised into the tailnet (usually the VPC CIDR). */
+    readonly routes: string[];
+    /** Device name shown in the tailnet. Default: "connector". */
+    readonly hostname?: string;
+    /** Self-auth at boot (single-use key, no stored secret). Cross-account:
+     *  `hub.connectorKeyMinter(...)` + the hub's grantConnectorAccount — its ARN
+     *  carries the hub region the mint step addresses. */
+    readonly minter: lambda.IFunction;
+    /** Container Insights on the connector cluster (Security Hub ECS.12);
+     *  per-metric cost. Default false. */
+    readonly containerInsights?: boolean;
+    /** Run the connector from a copy of the Tailscale image in this account's own registry, made at
+     *  deploy, so a restart never depends on the public registry. Default false. */
+    readonly mirrorImages?: boolean;
+}
+/** In-VPC subnet router, one per VPC; dials OUT only. Grants decide who may
+ *  route here — the resource's SG still decides what the VPC accepts. */
+export declare class TailnetConnector extends Construct {
+    readonly securityGroup: ec2.SecurityGroup;
+    constructor(scope: Construct, id: string, props: TailnetConnectorProps);
+}