@lsts_tech/infra 1.0.0 → 1.0.2

package/docs/CONFIGURATION.md

@@ -1,23 +1,29 @@
 # Configuration Guide
 
-## Environment Variables
+## Core Environment Variables
 
 The scaffolded `infra.config.ts` is environment-driven.
 
 | Variable | Required | Description |
 |---|---|---|
+| `INFRA_PROFILE` | No | `next-only`, `next-expo`, `expo-web` |
 | `INFRA_APP_NAME` | No | SST app name |
+| `INFRA_USE_EXTERNAL_CERTS` | No | `true` to force use of `INFRA_*_CERT_ARN_*` values |
 | `INFRA_ROOT_DOMAIN` | Yes | Root domain for stage resolution |
+| `INFRA_HOSTED_ZONE_DOMAIN` | No | Explicit Route53 zone domain override (eg. `alternun.co`) |
 | `INFRA_PIPELINE_REPO` | No | GitHub repo in `owner/repo` format |
 | `INFRA_PIPELINE_PREFIX` | No | Prefix for pipeline names |
 | `INFRA_PROJECT_TAG` | No | Resource tag value |
-| `INFRA_PIPELINES` | No | Pipeline stages CSV: `production,dev,mobile` |
+| `INFRA_PIPELINES` | No | Pipeline stage CSV: `production,dev,mobile` |
 | `INFRA_PIPELINE_BRANCH_PROD` | No | Branch for production pipeline |
 | `INFRA_PIPELINE_BRANCH_DEV` | No | Branch for dev pipeline |
 | `INFRA_PIPELINE_BRANCH_MOBILE` | No | Branch for mobile pipeline |
-| `INFRA_ENABLE_EXPO_SITE` | No | `true` enables Expo `StaticSite` deploy |
+| `INFRA_PIPELINES_CONFIG_PATH` | No | Runtime pipeline config JSON path |
+| `INFRA_CREATE_PIPELINES` | No | `true` allows production deploy to create/update pipelines |
+| `INFRA_PIPELINE_PERMISSIONS_MODE` | No | `admin` or `least-privilege` for CodeBuild IAM |
+| `INFRA_ENABLE_EXPO_SITE` | No | `true` enables Expo site for `next-expo` profile |
 
-### Domain Overrides (Optional)
+## Domain Overrides (Optional)
 
 | Variable | Description |
 |---|---|
@@ -28,19 +34,7 @@ The scaffolded `infra.config.ts` is environment-driven.
 | `INFRA_EXPO_DOMAIN_DEV` | Expo dev domain |
 | `INFRA_EXPO_DOMAIN_MOBILE` | Expo mobile-stage domain |
 
-## DNS Helper Script Overrides
-
-These are consumed by `predeploy-checks.sh` and `postdeploy-update-dns.sh` (typically via `buildspec.yml`):
-
-| Variable | Description |
-|---|---|
-| `DOMAIN_ROOT` | Base/root domain |
-| `DOMAIN_PRODUCTION` | Explicit production domain override |
-| `DOMAIN_DEV` | Explicit dev domain override |
-| `DOMAIN_MOBILE` | Explicit mobile domain override |
-| `DOMAIN_CUSTOM` | Explicit override for non-standard stage names |
-
-### Certificate Reuse (Optional)
+## Certificate Reuse (Optional)
 
 | Variable | Description |
 |---|---|
@@ -51,28 +45,77 @@ These are consumed by `predeploy-checks.sh` and `postdeploy-update-dns.sh` (typi
 | `INFRA_EXPO_CERT_ARN_DEV` | Existing ACM cert ARN for expo dev domain |
 | `INFRA_EXPO_CERT_ARN_MOBILE` | Existing ACM cert ARN for expo mobile-stage domain |
 
-## SST Secrets
+## Runtime Pipeline Config
 
-Minimum secrets from the default template:
+`INFRA_PIPELINES_CONFIG_PATH` defaults to `config/pipelines.json`.
+If present, `scripts/ensure-pipelines.sh` reads it to drive stage enablement/branches/repos.
 
-- `DatabaseUrl`
-- `AuthSecret`
+Example (`config/pipelines.json`):
 
-Set per stage:
+```json
+{
+  "pipelines": {
+    "production": { "enabled": true, "branch": "main", "repo": "myorg/web" },
+    "dev": { "enabled": true, "branch": "develop", "repo": "myorg/web" },
+    "mobile": { "enabled": false, "branch": "mobile", "repo": "myorg/mobile" }
+  }
+}
+```
+
+## Pipeline Mutation Safety
+
+Normal deploys should keep:
 
 ```bash
-npx sst secrets set DatabaseUrl "postgresql://..." --stage dev
-npx sst secrets set AuthSecret "your-secret" --stage dev
+INFRA_CREATE_PIPELINES=false
 ```
 
-## Pipeline Provisioning
-
-1. Ensure your `INFRA_PIPELINES` and branch variables are correct.
-2. Deploy once (`sst deploy`) from the infra package.
-3. Run:
+To intentionally create/update pipelines:
 
 ```bash
 APPROVE=true bash scripts/ensure-pipelines.sh
 ```
 
-This script checks for missing pipelines and creates them by running stage-specific SST deploys.
+This script flips `INFRA_CREATE_PIPELINES=true` only for explicit pipeline-creation deploys.
+
+## Delegated Subdomain / Parent Zone Setup
+
+For setups like:
+
+- app domain: `airs.alternun.co`
+- stage domain: `dev.airs.alternun.co`
+- hosted zone available in AWS: `alternun.co`
+
+set:
+
+```bash
+INFRA_ROOT_DOMAIN=airs.alternun.co
+INFRA_HOSTED_ZONE_DOMAIN=alternun.co
+```
+
+Helper scripts also fallback to parent zones automatically during Route53 checks/updates.
+
+## Local Private Config
+
+Scaffolded defaults include:
+
+- `config/private.example.json`
+- `.gitignore` rules:
+  - `config/*.json`
+  - `!config/*.example.json`
+
+Use `config/private.json` for local-only deployment metadata/secrets (never commit it).
+
+## SST Secrets
+
+Minimum secrets from Next.js templates:
+
+- `DatabaseUrl`
+- `AuthSecret`
+
+Set per stage:
+
+```bash
+npx sst secret set DatabaseUrl "postgresql://..." --stage dev
+npx sst secret set AuthSecret "your-secret" --stage dev
+```

package/docs/EXAMPLES.md

@@ -6,4 +6,8 @@
 - [`next-and-expo/infra.config.ts`](../examples/next-and-expo/infra.config.ts)
   Next.js + Expo web static site + production/dev/mobile pipelines.
 
-Both examples are provider-scoped to AWS for v1.0.0.
+- [`delegated-subdomain/infra.config.ts`](../examples/delegated-subdomain/infra.config.ts)
+  Delegated subdomain deployment with explicit parent hosted zone fallback:
+  `airs.alternun.co` + `dev.airs.alternun.co` using hosted zone `alternun.co`.
+
+All examples are AWS-scoped for v1.x.

package/examples/delegated-subdomain/infra.config.ts

@@ -0,0 +1,102 @@
+import { resolveDomain, createNextSite, createExpoSite, createPipeline } from "@lsts_tech/infra";
+
+type PipelineStage = "production" | "dev" | "mobile";
+
+const secrets = {
+  DatabaseUrl: new sst.Secret("DatabaseUrl"),
+  AuthSecret: new sst.Secret("AuthSecret"),
+};
+
+const rootDomain = process.env.INFRA_ROOT_DOMAIN ?? "airs.alternun.co";
+const hostedZoneDomain = process.env.INFRA_HOSTED_ZONE_DOMAIN ?? "alternun.co";
+const pipelineRepo = process.env.INFRA_PIPELINE_REPO ?? "myorg/myrepo";
+const pipelinePrefix = process.env.INFRA_PIPELINE_PREFIX ?? "airs";
+const createPipelines = (process.env.INFRA_CREATE_PIPELINES ?? "false") === "true";
+
+const webStageMap: Record<string, string> = {
+  production: process.env.INFRA_WEB_DOMAIN_PRODUCTION ?? rootDomain,
+  dev: process.env.INFRA_WEB_DOMAIN_DEV ?? `dev.${rootDomain}`,
+  mobile: process.env.INFRA_WEB_DOMAIN_MOBILE ?? `api.${rootDomain}`,
+};
+
+const expoStageMap: Record<string, string> = {
+  production: process.env.INFRA_EXPO_DOMAIN_PRODUCTION ?? `mobile.${rootDomain}`,
+  dev: process.env.INFRA_EXPO_DOMAIN_DEV ?? `dev.mobile.${rootDomain}`,
+  mobile: process.env.INFRA_EXPO_DOMAIN_MOBILE ?? `preview.mobile.${rootDomain}`,
+};
+
+const selectedPipelines = (process.env.INFRA_PIPELINES ?? "production,dev,mobile")
+  .split(",")
+  .map((value) => value.trim().toLowerCase())
+  .filter((value): value is PipelineStage => value === "production" || value === "dev" || value === "mobile");
+
+export function createInfrastructure() {
+  const stage = $app.stage;
+
+  const webDomain = resolveDomain({
+    rootDomain,
+    stage,
+    stageMap: webStageMap,
+    hostedZoneDomain,
+  });
+
+  const web = createNextSite({
+    appPath: "../../apps/web",
+    id: `web-${stage}`,
+    domain: webDomain.domain,
+    environment: {
+      NEXT_PUBLIC_APP_URL: `https://${webDomain.domainName}`,
+      DATABASE_URL: secrets.DatabaseUrl.value,
+      AUTH_SECRET: secrets.AuthSecret.value,
+    },
+  });
+
+  const expoDomain = resolveDomain({
+    rootDomain,
+    stage,
+    stageMap: expoStageMap,
+    hostedZoneDomain,
+  });
+
+  const expo = createExpoSite({
+    appPath: "../../apps/mobile",
+    id: `mobile-${stage}`,
+    domain: expoDomain.domain,
+    environment: {
+      EXPO_PUBLIC_API_URL: `https://${webDomain.domainName}/api`,
+    },
+  });
+
+  const outputs: Record<string, unknown> = {
+    siteUrl: web.url,
+    domain: webDomain.domainName,
+    mobileUrl: expo.url,
+    mobileDomain: expoDomain.domainName,
+    hostedZoneDomain,
+  };
+
+  if (stage === "production" && createPipelines) {
+    for (const pipelineStage of selectedPipelines) {
+      const branch =
+        pipelineStage === "production"
+          ? process.env.INFRA_PIPELINE_BRANCH_PROD ?? "main"
+          : pipelineStage === "dev"
+            ? process.env.INFRA_PIPELINE_BRANCH_DEV ?? "develop"
+            : process.env.INFRA_PIPELINE_BRANCH_MOBILE ?? "mobile";
+
+      const suffix = pipelineStage === "production" ? "prod" : pipelineStage;
+      const pipeline = createPipeline({
+        name: `${pipelinePrefix}-${suffix}`,
+        repo: pipelineRepo,
+        branch,
+        stage: pipelineStage,
+        permissionsMode:
+          process.env.INFRA_PIPELINE_PERMISSIONS_MODE === "least-privilege" ? "least-privilege" : "admin",
+      });
+
+      outputs[`${pipelineStage}PipelineName`] = pipeline.pipelineName;
+    }
+  }
+
+  return outputs;
+}

package/examples/next-and-expo/infra.config.ts

@@ -1,19 +1,27 @@
 import { resolveDomain, createNextSite, createExpoSite, createPipeline } from "@lsts_tech/infra";
 
+type PipelineStage = "production" | "dev" | "mobile";
+
 const secrets = {
   DatabaseUrl: new sst.Secret("DatabaseUrl"),
   AuthSecret: new sst.Secret("AuthSecret"),
 };
 
+const rootDomain = process.env.INFRA_ROOT_DOMAIN ?? "example.com";
+const hostedZoneDomain = process.env.INFRA_HOSTED_ZONE_DOMAIN || undefined;
+const createPipelines = (process.env.INFRA_CREATE_PIPELINES ?? "false") === "true";
+const pipelinePermissionsMode =
+  process.env.INFRA_PIPELINE_PERMISSIONS_MODE === "least-privilege" ? "least-privilege" : "admin";
+
 export function createInfrastructure() {
   const stage = $app.stage;
-  const rootDomain = process.env.INFRA_ROOT_DOMAIN ?? "example.com";
   const repo = process.env.INFRA_PIPELINE_REPO ?? "myorg/myrepo";
   const prefix = process.env.INFRA_PIPELINE_PREFIX ?? "myapp";
 
   const webDomain = resolveDomain({
     rootDomain,
     stage,
+    hostedZoneDomain,
     stageMap: {
       production: process.env.INFRA_WEB_DOMAIN_PRODUCTION ?? rootDomain,
       dev: process.env.INFRA_WEB_DOMAIN_DEV ?? `dev.${rootDomain}`,
@@ -40,6 +48,7 @@ export function createInfrastructure() {
   const expoDomain = resolveDomain({
     rootDomain,
     stage,
+    hostedZoneDomain,
     stageMap: {
       production: process.env.INFRA_EXPO_DOMAIN_PRODUCTION ?? `mobile.${rootDomain}`,
       dev: process.env.INFRA_EXPO_DOMAIN_DEV ?? `dev.mobile.${rootDomain}`,
@@ -68,36 +77,32 @@ export function createInfrastructure() {
     mobileDomain: expoDomain.domainName,
   };
 
-  if (stage === "production") {
-    const production = createPipeline({
-      name: `${prefix}-prod`,
-      repo,
-      branch: process.env.INFRA_PIPELINE_BRANCH_PROD ?? "main",
-      stage: "production",
-      projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
-    });
+  if (stage === "production" && createPipelines) {
+    const selected = (process.env.INFRA_PIPELINES ?? "production,dev,mobile")
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter((value): value is PipelineStage => value === "production" || value === "dev" || value === "mobile");
 
-    const dev = createPipeline({
-      name: `${prefix}-dev`,
-      repo,
-      branch: process.env.INFRA_PIPELINE_BRANCH_DEV ?? "develop",
-      stage: "dev",
-      projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
-    });
+    for (const pipelineStage of selected) {
+      const suffix = pipelineStage === "production" ? "prod" : pipelineStage;
+      const branch =
+        pipelineStage === "production"
+          ? process.env.INFRA_PIPELINE_BRANCH_PROD ?? "main"
+          : pipelineStage === "dev"
+            ? process.env.INFRA_PIPELINE_BRANCH_DEV ?? "develop"
+            : process.env.INFRA_PIPELINE_BRANCH_MOBILE ?? "mobile";
 
-    const mobile = createPipeline({
-      name: `${prefix}-mobile`,
-      repo,
-      branch: process.env.INFRA_PIPELINE_BRANCH_MOBILE ?? "mobile",
-      stage: "mobile",
-      projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
-    });
+      const pipeline = createPipeline({
+        name: `${prefix}-${suffix}`,
+        repo,
+        branch,
+        stage: pipelineStage,
+        projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
+        permissionsMode: pipelinePermissionsMode,
+      });
 
-    outputs.pipelines = {
-      production: production.pipelineName,
-      dev: dev.pipelineName,
-      mobile: mobile.pipelineName,
-    };
+      outputs[`${pipelineStage}PipelineName`] = pipeline.pipelineName;
+    }
   }
 
   return outputs;

package/examples/next-only/infra.config.ts

@@ -1,17 +1,25 @@
 import { resolveDomain, createNextSite, createPipeline } from "@lsts_tech/infra";
 
+type PipelineStage = "production" | "dev" | "mobile";
+
 const secrets = {
   DatabaseUrl: new sst.Secret("DatabaseUrl"),
   AuthSecret: new sst.Secret("AuthSecret"),
 };
 
+const rootDomain = process.env.INFRA_ROOT_DOMAIN ?? "example.com";
+const hostedZoneDomain = process.env.INFRA_HOSTED_ZONE_DOMAIN || undefined;
+const createPipelines = (process.env.INFRA_CREATE_PIPELINES ?? "false") === "true";
+const pipelinePermissionsMode =
+  process.env.INFRA_PIPELINE_PERMISSIONS_MODE === "least-privilege" ? "least-privilege" : "admin";
+
 export function createInfrastructure() {
   const stage = $app.stage;
-  const rootDomain = process.env.INFRA_ROOT_DOMAIN ?? "example.com";
 
   const { domain, domainName } = resolveDomain({
     rootDomain,
     stage,
+    hostedZoneDomain,
   });
 
   const { url } = createNextSite({
@@ -30,30 +38,35 @@ export function createInfrastructure() {
     domain: domainName,
   };
 
-  if (stage === "production") {
+  if (stage === "production" && createPipelines) {
     const repo = process.env.INFRA_PIPELINE_REPO ?? "myorg/myrepo";
     const prefix = process.env.INFRA_PIPELINE_PREFIX ?? "myapp";
 
-    const prod = createPipeline({
-      name: `${prefix}-prod`,
-      repo,
-      branch: process.env.INFRA_PIPELINE_BRANCH_PROD ?? "main",
-      stage: "production",
-      projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
-    });
-
-    const dev = createPipeline({
-      name: `${prefix}-dev`,
-      repo,
-      branch: process.env.INFRA_PIPELINE_BRANCH_DEV ?? "develop",
-      stage: "dev",
-      projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
-    });
-
-    outputs.pipelines = {
-      production: prod.pipelineName,
-      dev: dev.pipelineName,
-    };
+    const selected = (process.env.INFRA_PIPELINES ?? "production,dev")
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter((value): value is PipelineStage => value === "production" || value === "dev" || value === "mobile");
+
+    for (const pipelineStage of selected) {
+      const suffix = pipelineStage === "production" ? "prod" : pipelineStage;
+      const branch =
+        pipelineStage === "production"
+          ? process.env.INFRA_PIPELINE_BRANCH_PROD ?? "main"
+          : pipelineStage === "dev"
+            ? process.env.INFRA_PIPELINE_BRANCH_DEV ?? "develop"
+            : process.env.INFRA_PIPELINE_BRANCH_MOBILE ?? "mobile";
+
+      const pipeline = createPipeline({
+        name: `${prefix}-${suffix}`,
+        repo,
+        branch,
+        stage: pipelineStage,
+        projectTag: process.env.INFRA_PROJECT_TAG ?? prefix,
+        permissionsMode: pipelinePermissionsMode,
+      });
+
+      outputs[`${pipelineStage}PipelineName`] = pipeline.pipelineName;
+    }
   }
 
   return outputs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsts_tech/infra",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Reusable SST v3 infrastructure constructs for deploying Next.js and Expo web apps from monorepos.",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,10 @@
     "./stacks/Pipeline": {
       "types": "./dist/stacks/Pipeline.d.ts",
       "import": "./dist/stacks/Pipeline.js"
+    },
+    "./auth": {
+      "types": "./dist/src/auth/index.d.ts",
+      "import": "./dist/src/auth/index.js"
     }
   },
   "bin": {
@@ -75,6 +79,7 @@
     "deploy": "sst deploy",
     "deploy:dev": "sst deploy --stage dev",
     "deploy:prod": "sst deploy --stage production",
+    "doctor": "node dist/bin/init.js doctor --target .",
     "remove": "sst remove",
     "console": "sst console",
     "secrets": "sst secrets",
@@ -88,9 +93,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "sst": "^3.7.0",
+    "@edcalderon/auth": "^1.2.1",
     "@pulumi/aws": "^6.66.0",
-    "@pulumi/pulumi": "^3.145.0"
+    "@pulumi/pulumi": "^3.145.0",
+    "sst": "^3.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.9",
@@ -99,4 +105,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}