rastack 0.0.62 → 0.0.63

package/dist/rastack-init.js

@@ -63,12 +63,23 @@ const path = __importStar(require("path"));
 const config_1 = require("./deploy/config");
 const workflows_1 = require("./deploy/workflows");
 const io_1 = require("./deploy/io");
+function parseEnvFlag(value) {
+    const v = value.trim().toLowerCase();
+    if (v === "all" || v === "")
+        return [...config_1.ENV_NAMES];
+    if (config_1.ENV_NAMES.includes(v))
+        return [v];
+    console.error(`Unknown --env: expected dev | prod | all.`);
+    process.exit(1);
+}
 function parseFlags(argv) {
-    const patch = { github: {} };
+    const patch = { github: {}, environments: {} };
+    let envs = [...config_1.ENV_NAMES];
     let force = false;
     let noWorkflows = false;
     let noDeploy = false;
     let print = false;
+    const devPatch = () => { var _a; return ((_a = patch.environments).dev ?? (_a.dev = {})); };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         const next = () => argv[++i] ?? "";
@@ -85,6 +96,17 @@ function parseFlags(argv) {
             case "--branch":
                 patch.github.branch = next();
                 break;
+            case "--dev-branch":
+                devPatch().branch = next();
+                break;
+            case "--dev-proxy":
+            case "--dev-proxy-upstream":
+                // The dev external-API proxy upstream (a UAT/prod backend URL).
+                devPatch().proxyUpstream = next();
+                break;
+            case "--env":
+                envs = parseEnvFlag(next());
+                break;
             case "--region":
                 patch.region = next();
                 break;
@@ -114,7 +136,10 @@ function parseFlags(argv) {
                 }
         }
     }
-    return { patch, force, noWorkflows, noDeploy, print };
+    // Drop the scratch environments container when nothing was set on it.
+    if (patch.environments && !patch.environments.dev)
+        delete patch.environments;
+    return { patch, envs, force, noWorkflows, noDeploy, print };
 }
 /** Seed a config: existing file → flags → git remote → defaults. */
 function seedConfig(flags) {
@@ -151,6 +176,35 @@ async function promptMissing(cfg) {
         });
     });
 }
+/**
+ * Ensure `.env` is git-ignored and (re)write the generated `.env` with the
+ * current config, preserving any secrets a developer already added. Returns the
+ * repo-relative paths touched, for the written/skipped summary.
+ */
+function writeEnvAndGitignore(cfg) {
+    const touched = [];
+    // 1. git-ignore `.env` (append-merge; never duplicate or clobber).
+    const giAbs = path.join(process.cwd(), workflows_1.GITIGNORE_PATH);
+    const existingGi = fs.existsSync(giAbs)
+        ? fs.readFileSync(giAbs, "utf-8")
+        : "";
+    const nextGi = (0, workflows_1.gitignoreWith)(existingGi, workflows_1.ENV_PATH);
+    if (nextGi !== existingGi) {
+        fs.writeFileSync(giAbs, nextGi);
+        touched.push(workflows_1.GITIGNORE_PATH);
+    }
+    // 2. Upsert the generated RASTACK_* values into `.env` (secrets preserved).
+    const envAbs = path.join(process.cwd(), workflows_1.ENV_PATH);
+    const existingEnv = fs.existsSync(envAbs)
+        ? fs.readFileSync(envAbs, "utf-8")
+        : "";
+    const nextEnv = (0, workflows_1.applyEnvValues)(existingEnv, cfg);
+    if (nextEnv !== existingEnv) {
+        fs.writeFileSync(envAbs, nextEnv);
+        touched.push(workflows_1.ENV_PATH);
+    }
+    return touched;
+}
 /** Yes/no confirmation with a default of "no" — gates the cloud-mutating steps. */
 async function confirm(question) {
     return (0, io_1.withPrompt)(async (rl) => {
@@ -164,24 +218,36 @@ function table(rows) {
     return rows.map((r) => `    ${r.key.padEnd(width)}  ${r.value}`).join("\n");
 }
 /**
- * Read the app.yaml stack Outputs into a `DeployOutputs`, skipping any that are
- * not resolvable yet (best-effort — a freshly created stack has them all).
+ * Read one environment's app.yaml stack Outputs into a `DeployOutputs`, skipping
+ * any not resolvable yet (best-effort — a freshly created stack has them all).
  */
-function readAppOutputs(cfg) {
+function readEnvOutputs(cfg, env) {
+    const stackName = (0, config_1.resolveEnvironment)(cfg, env).stackName;
     const outputs = {};
     for (const { key, field } of config_1.APP_STACK_OUTPUTS) {
-        const value = (0, io_1.stackOutput)(cfg.stackName, key, cfg.region);
+        const value = (0, io_1.stackOutput)(stackName, key, cfg.region);
         if (value)
             outputs[field] = value;
     }
     return outputs;
 }
+/** Merge an environment's resolved outputs back into the config in the right slot. */
+function withEnvOutputs(cfg, env, outputs) {
+    return env === "prod"
+        ? (0, config_1.mergeConfig)(cfg, { outputs })
+        : (0, config_1.mergeConfig)(cfg, { environments: { dev: { outputs } } });
+}
+/** Human label for an environment ("dev" / "prod") plus its branch. */
+function envLabel(cfg, env) {
+    const e = (0, config_1.resolveEnvironment)(cfg, env);
+    return `${env} (${e.branch} → ${e.ghEnvironment})`;
+}
 /**
  * Print the exact commands `init` would run, without touching the cloud
  * (`--print`). The artifacts bucket is read from the bootstrap stack when the
  * AWS CLI is available, else shown as a placeholder.
  */
-function printPlan(cfg) {
+function printPlan(cfg, envs) {
     const bucket = (0, io_1.awsAvailable)()
         ? (0, io_1.stackOutput)((0, config_1.bootstrapStackName)(cfg), config_1.BOOTSTRAP_ARTIFACTS_OUTPUT, cfg.region)
         : null;
@@ -189,23 +255,32 @@ function printPlan(cfg) {
         artifactsBucket: bucket ?? "<ArtifactsBucketName from bootstrap stack>",
     });
     const appTemplate = (0, io_1.resolveDeployAsset)("app.yaml") ?? undefined;
-    console.log(`\n  Deployment plan (${cfg.stackName} @ ${cfg.region})\n`);
+    console.log(`\n  Deployment plan (${envs.join(" + ")} @ ${cfg.region})\n`);
     console.log(`  ── Prerequisite: the tier-0 bootstrap stack (${(0, config_1.bootstrapStackName)(cfg)}) must exist ──`);
     console.log(`  Create it once per account+region (init does not):  rastack bootstrap --region ${cfg.region}\n`);
-    console.log("  ── 1. Per-app backend (app.yaml) — what init deploys ──");
-    console.log("\n  " + (0, config_1.deployStackCommand)(withBucket, appTemplate) + "\n");
-    console.log("  ── 2. Wire these GitHub repo Variables from the stack Outputs ──");
-    console.log(table((0, config_1.repoVariables)(cfg).map((v) => ({
-        key: v.name,
-        value: v.value || `<${v.from}>`,
-    }))) + "\n");
+    console.log("  ── 1. Per-app backend (app.yaml) — one stack per environment ──");
+    for (const env of envs) {
+        const e = (0, config_1.resolveEnvironment)(withBucket, env);
+        console.log(`\n  # ${envLabel(withBucket, env)} — stack ${e.stackName}`);
+        console.log("  " + (0, config_1.deployStackCommandForEnv)(withBucket, env, appTemplate));
+    }
+    console.log("\n  ── 2. Wire each GitHub Environment's Variables from its stack Outputs ──");
+    for (const env of envs) {
+        const e = (0, config_1.resolveEnvironment)(cfg, env);
+        console.log(`\n  # GitHub Environment: ${e.ghEnvironment}`);
+        console.log(table((0, config_1.repoVariablesForEnv)(cfg, env).map((v) => ({
+            key: v.name,
+            value: v.value || `<${v.from}>`,
+        }))));
+    }
+    console.log("");
 }
 /**
  * Stand the infrastructure up: ensure the bootstrap stack + artifacts bucket,
  * upload the Lambda placeholder, deploy app.yaml, and read the Outputs back into
  * the config. Returns the config enriched with the resolved buckets + outputs.
  */
-async function standUp(cfg, interactive) {
+async function standUp(cfg, envs, interactive) {
     if (!(0, io_1.awsAvailable)()) {
         console.error("  ✗ the AWS CLI is not on PATH. Install it and configure credentials,\n" +
             "    or re-run with --print to see the commands, or --no-deploy to skip.");
@@ -229,13 +304,12 @@ async function standUp(cfg, interactive) {
         process.exit(1);
     }
     console.log(`  ✓ artifacts bucket: ${artifactsBucket}`);
-    // 2. Upload the placeholder the function is created from.
+    // 2. Upload the placeholder the function is created from (shared by all envs).
     console.log("\n▸ Uploading the Lambda placeholder bundle");
     if (!(0, io_1.uploadPlaceholder)(artifactsBucket, cfg.region)) {
         console.error("  ✗ Lambda placeholder bundle not found in the rastack package — cannot create the function.");
         process.exit(1);
     }
-    // 3. Deploy the per-app backend with the resolved bucket wired in.
     cfg = (0, config_1.mergeConfig)(cfg, {
         artifactsBucket,
         templatesBucket: templatesBucket ?? undefined,
@@ -246,22 +320,25 @@ async function standUp(cfg, interactive) {
             "    (`npm i -g rastack`) or run from the framework repo.");
         process.exit(1);
     }
-    console.log(`\n▸ Deploying ${cfg.stackName}`);
-    try {
-        (0, io_1.awsRun)((0, config_1.deployStackArgs)(cfg, appTemplate));
-    }
-    catch (err) {
-        console.error(`\n  ✗ aws cloudformation deploy failed for ${cfg.stackName}.\n    ${err.message}`);
-        process.exit(1);
+    // 3. Deploy one stack per environment — each with its own Cognito pool,
+    //    warehouse, Lambda and API — reading the Outputs back into the config.
+    for (const env of envs) {
+        const stackName = (0, config_1.resolveEnvironment)(cfg, env).stackName;
+        console.log(`\n▸ Deploying ${envLabel(cfg, env)} — ${stackName}`);
+        try {
+            (0, io_1.awsRun)((0, config_1.deployStackArgsForEnv)(cfg, env, appTemplate));
+        }
+        catch (err) {
+            console.error(`\n  ✗ aws cloudformation deploy failed for ${stackName}.\n    ${err.message}`);
+            process.exit(1);
+        }
+        cfg = withEnvOutputs(cfg, env, readEnvOutputs(cfg, env));
+        (0, io_1.saveConfig)(cfg);
     }
-    // 4. Read the Outputs back into the config so CI has them without a live lookup.
-    const outputs = readAppOutputs(cfg);
-    cfg = (0, config_1.mergeConfig)(cfg, { outputs });
-    (0, io_1.saveConfig)(cfg);
-    // 5. Connect the GitHub CLI and wire the repo Variables CI reads, so the FIRST
-    //    push actually ships. Without this the deploy-backend workflow's `if:
-    //    vars.AWS_DEPLOY_ROLE_ARN != ''` guard silently skips every run.
-    wireRepoVariables(cfg, interactive);
+    // 4. Connect the GitHub CLI and wire each environment's scoped Variables, so
+    //    the FIRST push actually ships. Without this the deploy-backend workflow's
+    //    `if: vars.AWS_DEPLOY_ROLE_ARN != ''` guard silently skips every run.
+    wireEnvironments(cfg, envs, interactive);
     return cfg;
 }
 /**
@@ -275,58 +352,97 @@ async function standUp(cfg, interactive) {
  * (and isn't) done.
  */
 const wiredVariables = new Set();
-function wireRepoVariables(cfg, interactive) {
-    const vars = (0, config_1.repoVariables)(cfg).filter((v) => v.value);
-    if (!vars.length)
+/** Key a wired Variable by its GitHub Environment so dev/prod don't collide. */
+function wiredKey(ghEnvironment, name) {
+    return `${ghEnvironment ?? ""}:${name}`;
+}
+/**
+ * Create each environment's GitHub Actions Environment and wire its scoped
+ * `AWS_DEPLOY_ROLE_ARN` / `AWS_REGION` Variables via `gh`, so the GitHub →
+ * Lambda pipeline is live for both dev and prod the moment `init` finishes.
+ */
+function wireEnvironments(cfg, envs, interactive) {
+    const anyValue = envs.some((env) => (0, config_1.repoVariablesForEnv)(cfg, env).some((v) => v.value));
+    if (!anyValue)
         return;
     if (!(0, io_1.ghAvailable)()) {
-        console.log("\n▸ GitHub CLI (`gh`) not found — skipping repo Variable wiring.\n" +
+        console.log("\n▸ GitHub CLI (`gh`) not found — skipping environment + Variable wiring.\n" +
             "  Install `gh` (https://cli.github.com) and re-run, or wire the\n" +
             "  Variables below by hand so pushes deploy.");
         return;
     }
-    // Connect `gh` to GitHub if it isn't already, so it can set the Variables.
+    // Connect `gh` to GitHub if it isn't already, so it can create environments.
     if (!(0, io_1.ghAuthenticated)()) {
         if (interactive) {
             console.log("\n▸ Connecting the GitHub CLI to your account (`gh auth login`)");
             (0, io_1.ghAuthLogin)();
         }
         if (!(0, io_1.ghAuthenticated)()) {
-            console.log("\n▸ GitHub CLI is not connected — skipping repo Variable wiring.\n" +
+            console.log("\n▸ GitHub CLI is not connected — skipping environment wiring.\n" +
                 "  Run `gh auth login`, then wire the Variables below by hand.");
             return;
         }
     }
-    console.log("\n▸ Wiring the GitHub repo Variables CI reads (via `gh`)");
-    for (const v of vars) {
-        const ok = (0, io_1.setRepoVariable)((0, config_1.ghVariableSetArgs)(cfg, v.name, v.value));
-        if (ok) {
-            wiredVariables.add(v.name);
-            console.log(`  ✓ set ${v.name}`);
+    console.log("\n▸ Creating GitHub Environments + wiring their Variables (via `gh`)");
+    for (const env of envs) {
+        const e = (0, config_1.resolveEnvironment)(cfg, env);
+        // Create the Environment first — a Variable can only be scoped to one that
+        // already exists. Idempotent (PUT), so re-running init is safe.
+        if (!(0, io_1.ghEnvironmentCreate)((0, config_1.ghEnvironmentCreateArgs)(cfg, e.ghEnvironment))) {
+            console.log(`  • could not create GitHub Environment ${e.ghEnvironment} — create it by hand`);
+            continue;
         }
-        else {
-            console.log(`  • could not set ${v.name} — wire it by hand (below)`);
+        for (const v of (0, config_1.repoVariablesForEnv)(cfg, env).filter((x) => x.value)) {
+            const ok = (0, io_1.setRepoVariable)((0, config_1.ghVariableSetArgs)(cfg, v.name, v.value, v.ghEnvironment));
+            if (ok) {
+                wiredVariables.add(wiredKey(v.ghEnvironment, v.name));
+                console.log(`  ✓ set ${e.ghEnvironment}/${v.name}`);
+            }
+            else {
+                console.log(`  • could not set ${e.ghEnvironment}/${v.name} — wire it by hand (below)`);
+            }
         }
     }
 }
-function printSummary(cfg) {
-    console.log(`\n  ✓ ${cfg.app} is deployed (${cfg.stackName} @ ${cfg.region})`);
-    if (cfg.outputs?.apiUrl)
-        console.log(`    API:  ${cfg.outputs.apiUrl}`);
+function printSummary(cfg, envs) {
+    console.log(`\n  ✓ ${cfg.app} is deployed @ ${cfg.region}`);
+    for (const env of envs) {
+        const e = (0, config_1.resolveEnvironment)(cfg, env);
+        console.log(`\n  ${env} — ${e.stackName}`);
+        if (e.outputs?.apiUrl)
+            console.log(`    API:        ${e.outputs.apiUrl}`);
+        if (e.outputs?.hostedUiUrl)
+            console.log(`    Hosted UI:  ${e.outputs.hostedUiUrl}`);
+        if (e.outputs?.userPoolId)
+            console.log(`    User Pool:  ${e.outputs.userPoolId}`);
+        if (e.outputs?.proxyUrl)
+            console.log(`    Proxy:      ${e.outputs.proxyUrl}`);
+    }
     // Only the Variables `init` could NOT wire itself remain a manual step.
-    const pending = (0, config_1.repoVariables)(cfg).filter((v) => !wiredVariables.has(v.name));
+    const pending = [];
+    for (const env of envs) {
+        const e = (0, config_1.resolveEnvironment)(cfg, env);
+        for (const v of (0, config_1.repoVariablesForEnv)(cfg, env)) {
+            if (!wiredVariables.has(wiredKey(v.ghEnvironment, v.name)))
+                pending.push({
+                    key: `${e.ghEnvironment}/${v.name}`,
+                    value: v.value || `<${v.from}>`,
+                });
+        }
+    }
     if (pending.length) {
-        console.log("\n  Wire these GitHub repo Variables so CI can ship code (Settings → Variables):");
-        console.log(table(pending.map((v) => ({
-            key: v.name,
-            value: v.value || `<${v.from}>`,
-        }))));
+        console.log("\n  Wire these per-environment GitHub Variables so CI can ship code\n" +
+            "  (Settings → Environments → <env> → Variables):");
+        console.log(table(pending));
     }
     else {
-        console.log("\n  ✓ wired the GitHub repo Variables CI reads (AWS_DEPLOY_ROLE_ARN, AWS_REGION).");
+        console.log("\n  ✓ wired every GitHub Environment's Variables (AWS_DEPLOY_ROLE_ARN, AWS_REGION).");
     }
-    console.log(`\n  Every push to ${cfg.github.branch} now ships code via \`rastack ci deploy\`` +
-        ` (also runnable locally as \`rastack deploy\`).\n`);
+    const dev = (0, config_1.resolveEnvironment)(cfg, "dev");
+    const prod = (0, config_1.resolveEnvironment)(cfg, "prod");
+    console.log(`\n  Pushes now ship code via \`rastack ci deploy\`:\n` +
+        `    ${prod.branch} → prod (${prod.ghEnvironment})   ${dev.branch} → dev (${dev.ghEnvironment})\n` +
+        `  Run one locally with \`rastack deploy --env dev\` / \`--env prod\`.\n`);
 }
 async function main(argv) {
     const flags = parseFlags(argv);
@@ -362,6 +478,10 @@ async function main(argv) {
         fs.writeFileSync(abs, f.content);
         written.push(f.path);
     }
+    // The `.env` (local app environment) + its `.gitignore` entry are standard —
+    // generated on every init, secrets preserved, refreshed with Outputs post-deploy.
+    for (const p of writeEnvAndGitignore(cfg))
+        written.push(p);
     console.log("");
     for (const w of written)
         console.log(`  ✓ wrote ${w}`);
@@ -369,7 +489,7 @@ async function main(argv) {
         console.log(`  • skipped ${s} (exists — pass --force to overwrite)`);
     // 2. Deploy (unless opted out).
     if (flags.print) {
-        printPlan(cfg);
+        printPlan(cfg, flags.envs);
         return;
     }
     if (flags.noDeploy) {
@@ -378,14 +498,20 @@ async function main(argv) {
         return;
     }
     if ((0, io_1.canPrompt)()) {
-        const ok = await confirm(`Deploy ${cfg.stackName} to AWS ${cfg.region} now? (requires the bootstrap stack to exist) [y/N]`);
+        const stacks = flags.envs
+            .map((env) => (0, config_1.resolveEnvironment)(cfg, env).stackName)
+            .join(" + ");
+        const ok = await confirm(`Deploy ${stacks} to AWS ${cfg.region} now? (requires the bootstrap stack to exist) [y/N]`);
         if (!ok) {
             console.log("\n  Skipped the deploy. Re-run to deploy, or `rastack init --print` for the commands.\n");
             return;
         }
     }
-    cfg = await standUp(cfg, (0, io_1.canPrompt)());
-    printSummary(cfg);
+    cfg = await standUp(cfg, flags.envs, (0, io_1.canPrompt)());
+    // Refresh `.env` with the resolved stack Outputs (API URLs, pool/client ids).
+    for (const p of writeEnvAndGitignore(cfg))
+        console.log(`  ✓ updated ${p}`);
+    printSummary(cfg, flags.envs);
 }
 if (require.main === module) {
     main(process.argv.slice(2)).catch((err) => {

package/dist/rastack.js

@@ -130,6 +130,7 @@ switch (command) {
     case "deploy":
         // Ship code to the Lambda — an alias for the CI code deploy. Infrastructure
         // is stood up once by `rastack init`; `deploy` only ever ships code.
+        // `--env dev|prod` picks which environment's function to update.
         run("rastack-ci.js", ["deploy", ...rest]);
         break;
     case "ci":

package/dist/templates/cloudformation/app.yaml

@@ -34,7 +34,44 @@ Parameters:
   GitHubBranch:
     Type: String
     Default: master
-    Description: Branch of GitHubRepo allowed to deploy.
+    Description: Branch of GitHubRepo allowed to deploy (used when GitHubEnvironment is blank).
+
+  GitHubEnvironment:
+    Type: String
+    Default: ""
+    Description: >
+      GitHub Actions **Environment** (e.g. development / production) this stack's
+      deploy role trusts. When set, the OIDC trust is scoped to
+      `…:environment:<name>` — the subject a job that declares `environment:` gets
+      — instead of a branch ref, so the dev and prod deploys can share a branch
+      set yet only assume their own environment's role. Blank keeps the legacy
+      branch-ref trust (`…:ref:refs/heads/<GitHubBranch>`). `rastack init` sets it
+      to development / production for the dev / prod stacks.
+
+  CallbackUrls:
+    Type: CommaDelimitedList
+    Default: "http://localhost:4321"
+    Description: >
+      Allowed OAuth redirect (callback) URLs for the Hosted UI app client. The
+      local `rastack dev` origin is the default so a developer can sign in against
+      this environment's real Cognito pool while developing; add your deployed
+      frontend origin(s) too.
+
+  LogoutUrls:
+    Type: CommaDelimitedList
+    Default: "http://localhost:4321"
+    Description: Allowed sign-out redirect URLs for the Hosted UI app client.
+
+  ExternalApiUpstream:
+    Type: String
+    Default: ""
+    Description: >
+      Base URL (no trailing slash) the **external-API proxy** forwards to —
+      typically a UAT or prod backend. When set, the stack adds a
+      Cognito-authorized `ANY /proxy/{proxy+}` route to the HTTP API that forwards
+      to `<upstream>/{proxy}`, so a locally-running app (signed in against this
+      pool) reaches external APIs only through the proxy, never directly. Blank
+      omits the proxy route + authorizer entirely.
 
   ArtifactsBucket:
     Type: String
@@ -87,6 +124,10 @@ Conditions:
   DeriveOIDCArn: !Equals [!Ref OIDCProviderArn, ""]
   ShouldTrailDataEvents: !Equals [!Ref EnableDataEventTrail, "true"]
   UseAdvancedSecurity: !Not [!Equals [!Ref AdvancedSecurity, "OFF"]]
+  # Scope the deploy-role trust to a GitHub Actions Environment when one is given.
+  TrustEnvironment: !Not [!Equals [!Ref GitHubEnvironment, ""]]
+  # Provision the external-API proxy route only when an upstream is configured.
+  HasProxy: !Not [!Equals [!Ref ExternalApiUpstream, ""]]
 
 Resources:
 
@@ -290,6 +331,20 @@ Resources:
         - ALLOW_USER_SRP_AUTH
         - ALLOW_REFRESH_TOKEN_AUTH
       PreventUserExistenceErrors: ENABLED
+      # Hosted UI (OAuth 2.0 Authorization Code + PKCE) — the flow rastack/auth's
+      # <CognitoAuthProvider> drives. Enabling it here lets a locally-running app
+      # (`rastack dev`) sign in against this environment's real Cognito pool.
+      SupportedIdentityProviders:
+        - COGNITO
+      AllowedOAuthFlowsUserPoolClient: true
+      AllowedOAuthFlows:
+        - code
+      AllowedOAuthScopes:
+        - openid
+        - email
+        - profile
+      CallbackURLs: !Ref CallbackUrls
+      LogoutURLs: !Ref LogoutUrls
       TokenValidityUnits:
         AccessToken: minutes
         IdToken: minutes
@@ -299,6 +354,15 @@ Resources:
       RefreshTokenValidity: 30
       EnableTokenRevocation: true
 
+  # Hosted UI domain — the browser sign-in surface. Prefix is globally unique via
+  # the account id. Both the deployed frontend and local `rastack dev` redirect
+  # here to authenticate against this environment's pool.
+  UserPoolDomain:
+    Type: AWS::Cognito::UserPoolDomain
+    Properties:
+      Domain: !Sub "${NamePrefix}-${AppName}-${AWS::AccountId}"
+      UserPoolId: !Ref UserPool
+
   IdentityPool:
     Type: AWS::Cognito::IdentityPool
     Properties:
@@ -494,6 +558,49 @@ Resources:
       Principal: apigateway.amazonaws.com
       SourceArn: !Sub "arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${HttpApi}/*/*"
 
+  # -- External-API proxy (optional) --------------------------------------------
+  # When ExternalApiUpstream is set, a Cognito-authorized `ANY /proxy/{proxy+}`
+  # route forwards to `<upstream>/{proxy}`. HTTP API prefers the more specific
+  # route, so `/proxy/*` goes here and everything else still hits the Rust Lambda
+  # via `$default`. The JWT authorizer means only callers holding a valid token
+  # from THIS environment's pool can use the proxy — so a local dev app signs in
+  # against the dev pool, then reaches UAT/prod externals only through here.
+  ProxyJwtAuthorizer:
+    Type: AWS::ApiGatewayV2::Authorizer
+    Condition: HasProxy
+    Properties:
+      ApiId: !Ref HttpApi
+      AuthorizerType: JWT
+      Name: !Sub "${NamePrefix}-${AppName}-cognito"
+      IdentitySource:
+        - "$request.header.Authorization"
+      JwtConfiguration:
+        Audience:
+          - !Ref UserPoolClient
+        Issuer: !Sub "https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}"
+
+  ProxyIntegration:
+    Type: AWS::ApiGatewayV2::Integration
+    Condition: HasProxy
+    Properties:
+      ApiId: !Ref HttpApi
+      IntegrationType: HTTP_PROXY
+      IntegrationMethod: ANY
+      # `{proxy}` is the greedy path variable captured by the route; the caller's
+      # Authorization header is forwarded so the upstream can authorize too.
+      IntegrationUri: !Sub "${ExternalApiUpstream}/{proxy}"
+      PayloadFormatVersion: "1.0"
+
+  ProxyRoute:
+    Type: AWS::ApiGatewayV2::Route
+    Condition: HasProxy
+    Properties:
+      ApiId: !Ref HttpApi
+      RouteKey: "ANY /proxy/{proxy+}"
+      Target: !Sub "integrations/${ProxyIntegration}"
+      AuthorizationType: JWT
+      AuthorizerId: !Ref ProxyJwtAuthorizer
+
   # -- Deploy role (GitHub OIDC) — code only ------------------------------------
   # CI assumes this to ship compiled code. It can UpdateFunctionCode on THIS one
   # function and read this app's SSM params — nothing else — with an explicit
@@ -518,7 +625,13 @@ Resources:
               StringEquals:
                 token.actions.githubusercontent.com:aud: sts.amazonaws.com
               StringLike:
-                token.actions.githubusercontent.com:sub: !Sub "repo:${GitHubOwner}/${GitHubRepo}:ref:refs/heads/${GitHubBranch}"
+                # An environment-gated GitHub job's OIDC subject is
+                # `repo:O/R:environment:<env>`, not `…:ref:refs/heads/<branch>`,
+                # so the trust must match the environment when one is set.
+                token.actions.githubusercontent.com:sub: !If
+                  - TrustEnvironment
+                  - !Sub "repo:${GitHubOwner}/${GitHubRepo}:environment:${GitHubEnvironment}"
+                  - !Sub "repo:${GitHubOwner}/${GitHubRepo}:ref:refs/heads/${GitHubBranch}"
       Policies:
         - PolicyName: update-function-code-only
           PolicyDocument:
@@ -602,6 +715,14 @@ Resources:
       Type: String
       Value: !Sub "https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}/.well-known/jwks.json"
 
+  ParamHostedUiUrl:
+    Type: AWS::SSM::Parameter
+    DependsOn: UserPoolDomain
+    Properties:
+      Name: !Sub "/rastack/${AppName}/hosted-ui-url"
+      Type: String
+      Value: !Sub "https://${NamePrefix}-${AppName}-${AWS::AccountId}.auth.${AWS::Region}.amazoncognito.com"
+
 Outputs:
   ApiUrl:
     Description: Base URL of the deployed API (set as the frontend's remote base).
@@ -627,9 +748,19 @@ Outputs:
   JwksUrl:
     Description: JWKS to bake into the Lambda bundle at build time.
     Value: !Sub "https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}/.well-known/jwks.json"
+  UserPoolDomain:
+    Description: Cognito Hosted UI domain prefix (scheme-less).
+    Value: !Ref UserPoolDomain
+  HostedUiUrl:
+    Description: Cognito Hosted UI base URL — browser sign-in / `rastack dev` auth.
+    Value: !Sub "https://${NamePrefix}-${AppName}-${AWS::AccountId}.auth.${AWS::Region}.amazoncognito.com"
   WarehouseBucketName:
     Description: S3 Iceberg warehouse — the system of record.
     Value: !Ref WarehouseBucket
   AuditLogBucketName:
     Description: S3 access logs + CloudTrail data events for the warehouse.
     Value: !Ref AuditLogBucket
+  ProxyUrl:
+    Condition: HasProxy
+    Description: Base URL of the Cognito-authorized external-API proxy (when enabled).
+    Value: !Sub "https://${HttpApi}.execute-api.${AWS::Region}.amazonaws.com/proxy"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",