@openhi/constructs 0.0.121 → 0.0.122

package/lib/index.d.mts

@@ -20,7 +20,7 @@ import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as rds from 'aws-cdk-lib/aws-rds';
 import { HostedZone, HostedZoneProps, IHostedZone, HostedZoneAttributes } from 'aws-cdk-lib/aws-route53';
 import { StringParameterProps, StringParameter } from 'aws-cdk-lib/aws-ssm';
-import { Distribution, DistributionProps, CachePolicyProps } from 'aws-cdk-lib/aws-cloudfront';
+import { Distribution, DistributionProps, CachePolicyProps, BehaviorOptions } from 'aws-cdk-lib/aws-cloudfront';
 import { HostingMode } from './static-hosting.viewer-request-handler.mjs';
 export { C as CascadeChunkInput, a as CascadeFinalizeInput, b as CascadeFinalizeOutput, c as CascadeListInput, d as CascadeListOutput, O as OWNING_DELETE_CASCADE_CONSUMER_NAME, e as OWNING_DELETE_CASCADE_DEFAULT_CONCURRENCY, f as OWNING_DELETE_CASCADE_STUCK_THRESHOLD_MINUTES, g as OWNING_DELETE_OPS_EVENT_BUS_ENV_VAR } from './events-CjS-sm0W.mjs';
 import { StateMachine } from 'aws-cdk-lib/aws-stepfunctions';
@@ -33,6 +33,38 @@ export { ControlPlaneOwningDeleteCompleteV1, ControlPlaneOwningDeleteCompleteV1D
 import '@aws-sdk/client-dynamodb';
 import 'aws-lambda';
 
+/**
+ * Inputs required to compute the deterministic branch hash that
+ * scopes per-branch resources within an OpenHI deployment target.
+ *
+ * @public
+ */
+interface ComputeBranchHashOptions {
+    /** Application name (e.g. "openhi"). */
+    readonly appName: string;
+    /** Deployment target role identifier (e.g. "primary", "secondary"). */
+    readonly deploymentTargetRole: string;
+    /** AWS account id the deployment targets. */
+    readonly account: string;
+    /** AWS region the deployment targets. */
+    readonly region: string;
+    /** Git branch name driving this deployment. */
+    readonly branchName: string;
+}
+/**
+ * Compute the deterministic branch hash used by `OpenHiService` to scope
+ * per-branch resources. Every `DiscoverableStringParameter` published by
+ * an OpenHI service uses this hash as the branch segment of its SSM
+ * path: `/{version}/{branchHash}/{serviceType}/{account}/{region}/{paramName}`.
+ *
+ * Exporting the helper lets external tooling compute the same SSM
+ * prefix the CDK stacks publish to without re-implementing — and silently
+ * drifting from — the inlined math.
+ *
+ * @public
+ */
+declare const computeBranchHash: (options: ComputeBranchHashOptions) => string;
+
 /**
  * Properties for creating an OpenHiStage instance.
  */
@@ -1125,6 +1157,40 @@ interface StaticHostingProps {
      * SSM parameter descriptions.
      */
     readonly description?: string;
+    /**
+     * When supplied, the distribution proxies `/api/*` to the supplied REST
+     * API custom domain (e.g. `api.example.com`). Two CloudFront behaviors
+     * are added:
+     *
+     * - `/api/control/runtime-config` — cached for `runtimeConfigCacheTtl`
+     *   (default 5min) with the `v` query-string parameter in the cache key,
+     *   so the admin-console's bundle-hash-driven cache buster reaches a hot
+     *   CDN cache on every deploy without manual invalidation.
+     * - `/api/*` — `CachePolicy.CACHING_DISABLED`, all methods allowed,
+     *   `OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER` so CloudFront
+     *   sets the Host header to the origin's custom domain (required for
+     *   API Gateway's custom-domain mapping).
+     *
+     * Neither behavior is wired through the viewer-request edge Lambda —
+     * SPA path rewriting only applies to the default S3 origin.
+     *
+     * @default - no REST API proxy; the distribution serves S3 only
+     */
+    readonly restApi?: {
+        /**
+         * REST API custom-domain hostname (no scheme — e.g. `api.example.com`).
+         */
+        readonly domainName: string;
+        /**
+         * Default / max TTL for the cached `/api/control/runtime-config` response.
+         *
+         * @default 5 minutes default, 1 hour max
+         */
+        readonly runtimeConfigCacheTtl?: {
+            readonly defaultTtl?: Duration;
+            readonly maxTtl?: Duration;
+        };
+    };
 }
 /**
  * Static hosting: S3 bucket (private) + CloudFront distribution with Origin
@@ -1154,6 +1220,12 @@ declare class StaticHosting extends Construct {
     readonly distribution: Distribution;
     readonly viewerRequestHandler: NodejsFunction;
     constructor(scope: Construct, id: string, props?: StaticHostingProps);
+    /**
+     * Builds the `/api/*` and `/api/control/runtime-config` behaviors backed
+     * by the REST API custom-domain origin. Returns `undefined` when no
+     * `restApi` prop is supplied so the Distribution stays S3-only.
+     */
+    protected buildRestApiBehaviors(branchHash: string, restApi: StaticHostingProps["restApi"]): Record<string, BehaviorOptions> | undefined;
 }
 
 interface ProvisionDefaultWorkspaceLambdaProps {
@@ -1523,18 +1595,50 @@ declare class OpenHiGlobalService extends OpenHiService {
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/services/open-hi-rest-api-service.md
  */
+/**
+ * Caller-supplied portion of the runtime-config payload exposed through the
+ * public `GET /control/runtime-config` route. The three Cognito IDs are
+ * resolved inside the service via SSM lookups against the auth stack, so the
+ * caller only supplies the values the service cannot derive itself: the
+ * OAuth redirect URI (depends on the website's domain) and the API base URL
+ * (depends on the integration path the website's CloudFront uses).
+ */
+interface OpenHiRestApiRuntimeConfig {
+    /** OAuth redirect URI registered on the User Pool client (e.g. https://admin.example.com/oauth/callback). */
+    readonly cognitoRedirectUri: string;
+    /** Base URL the admin-console uses to reach the REST API (typically a same-origin `/api` relative path). */
+    readonly apiBaseUrl: string;
+}
 interface OpenHiRestApiServiceProps extends OpenHiServiceProps {
     /**
      * Optional props passed through to the RootHttpApi (API Gateway HTTP API) construct.
      * Use corsPreflight (CDK CorsPreflightOptions) for CORS; other HttpApiProps (e.g. description, disableExecuteApiEndpoint) apply as well.
      */
     readonly rootHttpApiProps?: RootHttpApiProps;
+    /**
+     * Values exposed through the public `GET /control/runtime-config` route.
+     * When supplied, the service plumbs five `OPENHI_RUNTIME_CONFIG_*`
+     * environment variables to the REST API Lambda — the three Cognito IDs
+     * are resolved internally from the auth stack via SSM, and the two
+     * fields on this prop are passed verbatim. The website's CloudFront
+     * distribution proxies `/api/*` to this endpoint so the admin-console can
+     * fetch its bootstrap config same-origin and stay branch-agnostic.
+     *
+     * Omit to leave the route returning 500 (missing-env-var diagnostic).
+     */
+    readonly runtimeConfig?: OpenHiRestApiRuntimeConfig;
 }
 /**
  * SSM parameter name suffix for the REST API base URL.
  * Full parameter name is built via buildParameterName with serviceType REST_API.
  */
 declare const REST_API_BASE_URL_SSM_NAME = "REST_API_BASE_URL";
+/**
+ * SSM parameter name suffix for the REST API's custom domain (bare hostname,
+ * no scheme — e.g. `api.example.com`). Consumed by the website service as
+ * the CloudFront `/api/*` origin host.
+ */
+declare const REST_API_DOMAIN_NAME_SSM_NAME = "REST_API_DOMAIN_NAME";
 /**
  * REST API service stack: HTTP API, custom domain, and Lambda; exports base URL via SSM.
  * Resources are created in protected methods; subclasses may override to customize.
@@ -1550,6 +1654,13 @@ declare class OpenHiRestApiService extends OpenHiService {
      * Use in other stacks for E2E, scripts, or config.
      */
     static restApiBaseUrlFromConstruct(scope: Construct): string;
+    /**
+     * Returns the REST API's custom domain name (bare hostname, no scheme — e.g.
+     * `api.example.com`) by looking it up from SSM. Use as the host for a
+     * CloudFront `HttpOrigin` so the website's distribution can proxy `/api/*`
+     * to this stack's API Gateway without per-branch DNS knowledge.
+     */
+    static restApiDomainNameFromConstruct(scope: Construct): string;
     get serviceType(): string;
     /** Override so this.props is typed with this service's options (e.g. rootHttpApiProps). */
     props: OpenHiRestApiServiceProps;
@@ -1580,6 +1691,14 @@ declare class OpenHiRestApiService extends OpenHiService {
      * Override to customize.
      */
     protected createRestApiBaseUrlParameter(apiDomainName: string): void;
+    /**
+     * Creates the SSM parameter exposing the REST API's custom domain (bare
+     * hostname, no scheme). Consumed by the website service as the CloudFront
+     * `/api/*` origin host.
+     * Look up via {@link OpenHiRestApiService.restApiDomainNameFromConstruct}.
+     * Override to customize.
+     */
+    protected createRestApiDomainNameParameter(apiDomainName: string): void;
     /**
      * Creates the API Gateway custom domain name resource.
      * Override to customize.
@@ -1596,6 +1715,17 @@ declare class OpenHiRestApiService extends OpenHiService {
      * Override to customize.
      */
     protected createRootHttpApi(domainName: DomainName): RootHttpApi;
+    /**
+     * Builds the `OPENHI_RUNTIME_CONFIG_*` env-var map the REST API Lambda
+     * exposes through `GET /control/runtime-config`. Returns `undefined` when
+     * the `runtimeConfig` prop is omitted so no env vars are set.
+     *
+     * The three Cognito IDs are resolved via SSM lookups against the auth
+     * stack from a dedicated sub-scope (`runtime-config`) so they don't
+     * collide with the user-pool / user-pool-client constructs already
+     * created in {@link createRootHttpApi}.
+     */
+    protected resolveRuntimeConfigEnvVars(): Record<string, string> | undefined;
 }
 
 /**
@@ -1975,6 +2105,26 @@ interface OpenHiWebsiteServiceProps extends OpenHiServiceProps {
      * @default true
      */
     readonly createStaticContent?: boolean;
+    /**
+     * When `true`, the website's CloudFront distribution proxies `/api/*` to
+     * the REST API service deployed for this branch. The API custom-domain
+     * hostname is resolved at synth time via SSM
+     * ({@link OpenHiRestApiService.restApiDomainNameFromConstruct}), so the
+     * REST API stack must have written its `REST_API_DOMAIN_NAME` SSM
+     * parameter at least once before the website stack updates — the
+     * workflow already orders these deploys (rest-api → website).
+     *
+     * Used together with the admin-console's runtime-config fetch (which
+     * calls `/api/control/runtime-config` same-origin) so the React bundle
+     * stays branch-agnostic.
+     *
+     * Only takes effect when `createHostingInfrastructure` is also true,
+     * since the additional CloudFront behaviors live on the release-branch
+     * distribution; feature-branch deploys share that distribution.
+     *
+     * @default false
+     */
+    readonly restApi?: boolean;
 }
 /**
  * SSM parameter name suffix for the website's full domain
@@ -2069,27 +2219,32 @@ declare class OpenHiWebsiteService extends OpenHiService {
         certificate: ICertificate;
         hostedZone: IHostedZone;
     }): StaticHosting;
+    /**
+     * Resolves the REST API custom-domain hostname from the rest-api stack's
+     * `REST_API_DOMAIN_NAME` SSM parameter. Wrapped in a private method so
+     * it can be overridden / stubbed in subclasses and tests.
+     */
+    protected resolveRestApi(): {
+        domainName: string;
+    };
     /**
      * Creates the SSM parameter that publishes the website's full domain.
      * Look up via {@link OpenHiWebsiteService.fullDomainFromConstruct}.
      */
     protected createFullDomainParameter(): void;
     /**
-     * Creates the StaticContent uploader. Always created so feature-branch
-     * deploys can publish content to their own sub-domain folder against the
-     * release-branch bucket.
-     *
-     * The destination bucket is resolved here so the construct never has to
-     * branch on release-vs-feature: on the release branch we pass the
-     * just-created {@link staticHosting} bucket directly (no SSM round-trip
-     * within a single stack); on every other branch we look up the bucket
-     * ARN published by the release-branch deploy, addressed against
-     * {@link OpenHiService.releaseBranchHash}.
+     * Creates the StaticContent uploader. Receives the resolved static-hosting
+     * bucket from the constructor — on the release-branch deploy this is the
+     * just-created {@link staticHosting} bucket (no SSM round-trip within a
+     * single stack); on every other deploy it is imported from the bucket ARN
+     * the release-branch deploy publishes to SSM, addressed against
+     * {@link OpenHiService.releaseBranchHash}. See
+     * {@link resolveStaticHostingBucket}.
      */
-    protected createStaticContent(): StaticContent;
+    protected createStaticContent(bucket: IBucket): StaticContent;
     /**
      * Returns an {@link IBucket} pointing at the static-hosting bucket the
-     * uploader writes to. On the release-branch deploy this is the bucket
+     * uploaders write to. On the release-branch deploy this is the bucket
      * just provisioned by {@link staticHosting}; on every other deploy it's
      * imported from the bucket ARN the release-branch deploy publishes to
      * SSM, addressed against {@link OpenHiService.releaseBranchHash}.
@@ -2281,4 +2436,4 @@ declare class RenameCascadeWorkflow extends Construct {
     constructor(scope: Construct, props: RenameCascadeWorkflowProps);
 }
 
-export { type BuildParameterNameProps, ChildHostedZone, type ChildHostedZoneProps, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DEMO_DATA_PLANE_FIXTURES, DataEventBus, type DataEventBusOptions, DataStoreHistoricalArchive, type DataStoreHistoricalArchiveProps, DataStorePostgresReplica, type DataStorePostgresReplicaProps, type DemoWorkspaceDataPlaneFixtures, DiscoverableStringParameter, type DiscoverableStringParameterProps, DynamoDbDataStore, type DynamoDbDataStoreProps, type FhirCurrentResourceChangeDetail, type GrantConsumerOptions, HostingMode, OPENHI_TAG_SUFFIX_BRANCH_NAME, OPENHI_TAG_SUFFIX_REPO_NAME, OPENHI_TAG_SUFFIX_SERVICE_TYPE, OPENHI_TAG_SUFFIX_STAGE_TYPE, OpenHiApp, type OpenHiAppProps, OpenHiAuthService, type OpenHiAuthServiceProps, OpenHiDataService, type OpenHiDataServiceProps, OpenHiEnvironment, type OpenHiEnvironmentProps, OpenHiGlobalService, type OpenHiGlobalServiceProps, OpenHiGraphqlService, type OpenHiGraphqlServiceProps, OpenHiRestApiService, type OpenHiRestApiServiceProps, OpenHiService, type OpenHiServiceProps, type OpenHiServiceType, OpenHiStage, type OpenHiStageProps, OpenHiWebsiteService, type OpenHiWebsiteServiceProps, OpsEventBus, OwningDeleteCascadeLambdas, type OwningDeleteCascadeLambdasProps, OwningDeleteCascadeWorkflow, type OwningDeleteCascadeWorkflowProps, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PlatformDeployBridge, PlatformDeployBridgeLambda, type PlatformDeployBridgeLambdaProps, type PlatformDeployBridgeProps, PostAuthenticationLambda, PostConfirmationLambda, type PostConfirmationLambdaProps, PreTokenGenerationLambda, type PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambda, type ProvisionDefaultWorkspaceLambdaProps, REST_API_BASE_URL_SSM_NAME, RenameCascadeLambdas, type RenameCascadeLambdasProps, RenameCascadeWorkflow, type RenameCascadeWorkflowProps, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, SEED_SYSTEM_DATA_ACTOR_SYSTEM, SEED_SYSTEM_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR, SSM_PARAM_NAME_FULL_DOMAIN, STATIC_HOSTING_SERVICE_TYPE, SeedDemoDataLambda, type SeedDemoDataLambdaProps, SeedDemoDataWorkflow, type SeedDemoDataWorkflowProps, SeedSystemDataLambda, type SeedSystemDataLambdaProps, SeedSystemDataWorkflow, type SeedSystemDataWorkflowProps, StaticContent, type StaticContentProps, StaticHosting, type StaticHostingProps, UserOnboardingWorkflow, type UserOnboardingWorkflowProps, WorkflowDedupConsumerNameInvalidError, WorkflowDedupTable, WorkflowDedupTableDuplicateError, type WorkflowDedupTableProps, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName, getWorkflowDedupTableName, openHiTagKey };
+export { type BuildParameterNameProps, ChildHostedZone, type ChildHostedZoneProps, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, type ComputeBranchHashOptions, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DEMO_DATA_PLANE_FIXTURES, DataEventBus, type DataEventBusOptions, DataStoreHistoricalArchive, type DataStoreHistoricalArchiveProps, DataStorePostgresReplica, type DataStorePostgresReplicaProps, type DemoWorkspaceDataPlaneFixtures, DiscoverableStringParameter, type DiscoverableStringParameterProps, DynamoDbDataStore, type DynamoDbDataStoreProps, type FhirCurrentResourceChangeDetail, type GrantConsumerOptions, HostingMode, OPENHI_TAG_SUFFIX_BRANCH_NAME, OPENHI_TAG_SUFFIX_REPO_NAME, OPENHI_TAG_SUFFIX_SERVICE_TYPE, OPENHI_TAG_SUFFIX_STAGE_TYPE, OpenHiApp, type OpenHiAppProps, OpenHiAuthService, type OpenHiAuthServiceProps, OpenHiDataService, type OpenHiDataServiceProps, OpenHiEnvironment, type OpenHiEnvironmentProps, OpenHiGlobalService, type OpenHiGlobalServiceProps, OpenHiGraphqlService, type OpenHiGraphqlServiceProps, type OpenHiRestApiRuntimeConfig, OpenHiRestApiService, type OpenHiRestApiServiceProps, OpenHiService, type OpenHiServiceProps, type OpenHiServiceType, OpenHiStage, type OpenHiStageProps, OpenHiWebsiteService, type OpenHiWebsiteServiceProps, OpsEventBus, OwningDeleteCascadeLambdas, type OwningDeleteCascadeLambdasProps, OwningDeleteCascadeWorkflow, type OwningDeleteCascadeWorkflowProps, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PlatformDeployBridge, PlatformDeployBridgeLambda, type PlatformDeployBridgeLambdaProps, type PlatformDeployBridgeProps, PostAuthenticationLambda, PostConfirmationLambda, type PostConfirmationLambdaProps, PreTokenGenerationLambda, type PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambda, type ProvisionDefaultWorkspaceLambdaProps, REST_API_BASE_URL_SSM_NAME, REST_API_DOMAIN_NAME_SSM_NAME, RenameCascadeLambdas, type RenameCascadeLambdasProps, RenameCascadeWorkflow, type RenameCascadeWorkflowProps, RootGraphqlApi, type RootGraphqlApiProps, RootHostedZone, RootHttpApi, type RootHttpApiProps, RootWildcardCertificate, SEED_SYSTEM_DATA_ACTOR_SYSTEM, SEED_SYSTEM_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR, SSM_PARAM_NAME_FULL_DOMAIN, STATIC_HOSTING_SERVICE_TYPE, SeedDemoDataLambda, type SeedDemoDataLambdaProps, SeedDemoDataWorkflow, type SeedDemoDataWorkflowProps, SeedSystemDataLambda, type SeedSystemDataLambdaProps, SeedSystemDataWorkflow, type SeedSystemDataWorkflowProps, StaticContent, type StaticContentProps, StaticHosting, type StaticHostingProps, UserOnboardingWorkflow, type UserOnboardingWorkflowProps, WorkflowDedupConsumerNameInvalidError, WorkflowDedupTable, WorkflowDedupTableDuplicateError, type WorkflowDedupTableProps, buildFhirCurrentResourceChangeDetail, computeBranchHash, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName, getWorkflowDedupTableName, openHiTagKey };

package/lib/index.d.ts

@@ -19,7 +19,7 @@ import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as rds from 'aws-cdk-lib/aws-rds';
 import { HostedZone, HostedZoneProps, IHostedZone, HostedZoneAttributes } from 'aws-cdk-lib/aws-route53';
 import { StringParameterProps, StringParameter } from 'aws-cdk-lib/aws-ssm';
-import { Distribution, DistributionProps, CachePolicyProps } from 'aws-cdk-lib/aws-cloudfront';
+import { Distribution, DistributionProps, CachePolicyProps, BehaviorOptions } from 'aws-cdk-lib/aws-cloudfront';
 import { StateMachine } from 'aws-cdk-lib/aws-stepfunctions';
 import { RenamableEntityType } from '@openhi/workflows';
 export { ControlPlaneOwningDeleteCompleteV1, ControlPlaneOwningDeleteCompleteV1Detail, ControlPlaneOwningDeleteFailedV1, ControlPlaneOwningDeleteFailedV1Detail, ControlPlaneOwningDeleteV1, ControlPlaneOwningDeleteV1Detail, ControlPlaneRenameCompleteV1, ControlPlaneRenameCompleteV1Detail, ControlPlaneRenameFailedV1, ControlPlaneRenameFailedV1Detail, ControlPlaneRenameV1, ControlPlaneRenameV1Detail, OPENHI_DATA_SOURCE, OPENHI_OPS_SOURCE, OWNING_ENTITY_TYPE, OwningEntityType, PlatformDeploymentCompletedV1, PlatformSystemDataSeededV1, RENAMABLE_ENTITY_TYPE, RenamableEntityType } from '@openhi/workflows';
@@ -670,6 +670,38 @@ interface ProvisionDefaultWorkspaceRequestedDetail {
 }
 declare const buildProvisionDefaultWorkspaceRequestedDetail: (event: PostConfirmationTriggerEvent) => ProvisionDefaultWorkspaceRequestedDetail | undefined;
 
+/**
+ * Inputs required to compute the deterministic branch hash that
+ * scopes per-branch resources within an OpenHI deployment target.
+ *
+ * @public
+ */
+interface ComputeBranchHashOptions {
+    /** Application name (e.g. "openhi"). */
+    readonly appName: string;
+    /** Deployment target role identifier (e.g. "primary", "secondary"). */
+    readonly deploymentTargetRole: string;
+    /** AWS account id the deployment targets. */
+    readonly account: string;
+    /** AWS region the deployment targets. */
+    readonly region: string;
+    /** Git branch name driving this deployment. */
+    readonly branchName: string;
+}
+/**
+ * Compute the deterministic branch hash used by `OpenHiService` to scope
+ * per-branch resources. Every `DiscoverableStringParameter` published by
+ * an OpenHI service uses this hash as the branch segment of its SSM
+ * path: `/{version}/{branchHash}/{serviceType}/{account}/{region}/{paramName}`.
+ *
+ * Exporting the helper lets external tooling compute the same SSM
+ * prefix the CDK stacks publish to without re-implementing — and silently
+ * drifting from — the inlined math.
+ *
+ * @public
+ */
+declare const computeBranchHash: (options: ComputeBranchHashOptions) => string;
+
 /**
  * Properties for creating an OpenHiStage instance.
  */
@@ -1762,6 +1794,40 @@ interface StaticHostingProps {
      * SSM parameter descriptions.
      */
     readonly description?: string;
+    /**
+     * When supplied, the distribution proxies `/api/*` to the supplied REST
+     * API custom domain (e.g. `api.example.com`). Two CloudFront behaviors
+     * are added:
+     *
+     * - `/api/control/runtime-config` — cached for `runtimeConfigCacheTtl`
+     *   (default 5min) with the `v` query-string parameter in the cache key,
+     *   so the admin-console's bundle-hash-driven cache buster reaches a hot
+     *   CDN cache on every deploy without manual invalidation.
+     * - `/api/*` — `CachePolicy.CACHING_DISABLED`, all methods allowed,
+     *   `OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER` so CloudFront
+     *   sets the Host header to the origin's custom domain (required for
+     *   API Gateway's custom-domain mapping).
+     *
+     * Neither behavior is wired through the viewer-request edge Lambda —
+     * SPA path rewriting only applies to the default S3 origin.
+     *
+     * @default - no REST API proxy; the distribution serves S3 only
+     */
+    readonly restApi?: {
+        /**
+         * REST API custom-domain hostname (no scheme — e.g. `api.example.com`).
+         */
+        readonly domainName: string;
+        /**
+         * Default / max TTL for the cached `/api/control/runtime-config` response.
+         *
+         * @default 5 minutes default, 1 hour max
+         */
+        readonly runtimeConfigCacheTtl?: {
+            readonly defaultTtl?: Duration;
+            readonly maxTtl?: Duration;
+        };
+    };
 }
 /**
  * Static hosting: S3 bucket (private) + CloudFront distribution with Origin
@@ -1791,6 +1857,12 @@ declare class StaticHosting extends Construct {
     readonly distribution: Distribution;
     readonly viewerRequestHandler: NodejsFunction;
     constructor(scope: Construct, id: string, props?: StaticHostingProps);
+    /**
+     * Builds the `/api/*` and `/api/control/runtime-config` behaviors backed
+     * by the REST API custom-domain origin. Returns `undefined` when no
+     * `restApi` prop is supplied so the Distribution stays S3-only.
+     */
+    protected buildRestApiBehaviors(branchHash: string, restApi: StaticHostingProps["restApi"]): Record<string, BehaviorOptions> | undefined;
 }
 
 interface ProvisionDefaultWorkspaceLambdaProps {
@@ -2160,18 +2232,50 @@ declare class OpenHiGlobalService extends OpenHiService {
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/services/open-hi-rest-api-service.md
  */
+/**
+ * Caller-supplied portion of the runtime-config payload exposed through the
+ * public `GET /control/runtime-config` route. The three Cognito IDs are
+ * resolved inside the service via SSM lookups against the auth stack, so the
+ * caller only supplies the values the service cannot derive itself: the
+ * OAuth redirect URI (depends on the website's domain) and the API base URL
+ * (depends on the integration path the website's CloudFront uses).
+ */
+interface OpenHiRestApiRuntimeConfig {
+    /** OAuth redirect URI registered on the User Pool client (e.g. https://admin.example.com/oauth/callback). */
+    readonly cognitoRedirectUri: string;
+    /** Base URL the admin-console uses to reach the REST API (typically a same-origin `/api` relative path). */
+    readonly apiBaseUrl: string;
+}
 interface OpenHiRestApiServiceProps extends OpenHiServiceProps {
     /**
      * Optional props passed through to the RootHttpApi (API Gateway HTTP API) construct.
      * Use corsPreflight (CDK CorsPreflightOptions) for CORS; other HttpApiProps (e.g. description, disableExecuteApiEndpoint) apply as well.
      */
     readonly rootHttpApiProps?: RootHttpApiProps;
+    /**
+     * Values exposed through the public `GET /control/runtime-config` route.
+     * When supplied, the service plumbs five `OPENHI_RUNTIME_CONFIG_*`
+     * environment variables to the REST API Lambda — the three Cognito IDs
+     * are resolved internally from the auth stack via SSM, and the two
+     * fields on this prop are passed verbatim. The website's CloudFront
+     * distribution proxies `/api/*` to this endpoint so the admin-console can
+     * fetch its bootstrap config same-origin and stay branch-agnostic.
+     *
+     * Omit to leave the route returning 500 (missing-env-var diagnostic).
+     */
+    readonly runtimeConfig?: OpenHiRestApiRuntimeConfig;
 }
 /**
  * SSM parameter name suffix for the REST API base URL.
  * Full parameter name is built via buildParameterName with serviceType REST_API.
  */
 declare const REST_API_BASE_URL_SSM_NAME = "REST_API_BASE_URL";
+/**
+ * SSM parameter name suffix for the REST API's custom domain (bare hostname,
+ * no scheme — e.g. `api.example.com`). Consumed by the website service as
+ * the CloudFront `/api/*` origin host.
+ */
+declare const REST_API_DOMAIN_NAME_SSM_NAME = "REST_API_DOMAIN_NAME";
 /**
  * REST API service stack: HTTP API, custom domain, and Lambda; exports base URL via SSM.
  * Resources are created in protected methods; subclasses may override to customize.
@@ -2187,6 +2291,13 @@ declare class OpenHiRestApiService extends OpenHiService {
      * Use in other stacks for E2E, scripts, or config.
      */
     static restApiBaseUrlFromConstruct(scope: Construct): string;
+    /**
+     * Returns the REST API's custom domain name (bare hostname, no scheme — e.g.
+     * `api.example.com`) by looking it up from SSM. Use as the host for a
+     * CloudFront `HttpOrigin` so the website's distribution can proxy `/api/*`
+     * to this stack's API Gateway without per-branch DNS knowledge.
+     */
+    static restApiDomainNameFromConstruct(scope: Construct): string;
     get serviceType(): string;
     /** Override so this.props is typed with this service's options (e.g. rootHttpApiProps). */
     props: OpenHiRestApiServiceProps;
@@ -2217,6 +2328,14 @@ declare class OpenHiRestApiService extends OpenHiService {
      * Override to customize.
      */
     protected createRestApiBaseUrlParameter(apiDomainName: string): void;
+    /**
+     * Creates the SSM parameter exposing the REST API's custom domain (bare
+     * hostname, no scheme). Consumed by the website service as the CloudFront
+     * `/api/*` origin host.
+     * Look up via {@link OpenHiRestApiService.restApiDomainNameFromConstruct}.
+     * Override to customize.
+     */
+    protected createRestApiDomainNameParameter(apiDomainName: string): void;
     /**
      * Creates the API Gateway custom domain name resource.
      * Override to customize.
@@ -2233,6 +2352,17 @@ declare class OpenHiRestApiService extends OpenHiService {
      * Override to customize.
      */
     protected createRootHttpApi(domainName: DomainName): RootHttpApi;
+    /**
+     * Builds the `OPENHI_RUNTIME_CONFIG_*` env-var map the REST API Lambda
+     * exposes through `GET /control/runtime-config`. Returns `undefined` when
+     * the `runtimeConfig` prop is omitted so no env vars are set.
+     *
+     * The three Cognito IDs are resolved via SSM lookups against the auth
+     * stack from a dedicated sub-scope (`runtime-config`) so they don't
+     * collide with the user-pool / user-pool-client constructs already
+     * created in {@link createRootHttpApi}.
+     */
+    protected resolveRuntimeConfigEnvVars(): Record<string, string> | undefined;
 }
 
 /**
@@ -2612,6 +2742,26 @@ interface OpenHiWebsiteServiceProps extends OpenHiServiceProps {
      * @default true
      */
     readonly createStaticContent?: boolean;
+    /**
+     * When `true`, the website's CloudFront distribution proxies `/api/*` to
+     * the REST API service deployed for this branch. The API custom-domain
+     * hostname is resolved at synth time via SSM
+     * ({@link OpenHiRestApiService.restApiDomainNameFromConstruct}), so the
+     * REST API stack must have written its `REST_API_DOMAIN_NAME` SSM
+     * parameter at least once before the website stack updates — the
+     * workflow already orders these deploys (rest-api → website).
+     *
+     * Used together with the admin-console's runtime-config fetch (which
+     * calls `/api/control/runtime-config` same-origin) so the React bundle
+     * stays branch-agnostic.
+     *
+     * Only takes effect when `createHostingInfrastructure` is also true,
+     * since the additional CloudFront behaviors live on the release-branch
+     * distribution; feature-branch deploys share that distribution.
+     *
+     * @default false
+     */
+    readonly restApi?: boolean;
 }
 /**
  * SSM parameter name suffix for the website's full domain
@@ -2706,27 +2856,32 @@ declare class OpenHiWebsiteService extends OpenHiService {
         certificate: ICertificate;
         hostedZone: IHostedZone;
     }): StaticHosting;
+    /**
+     * Resolves the REST API custom-domain hostname from the rest-api stack's
+     * `REST_API_DOMAIN_NAME` SSM parameter. Wrapped in a private method so
+     * it can be overridden / stubbed in subclasses and tests.
+     */
+    protected resolveRestApi(): {
+        domainName: string;
+    };
     /**
      * Creates the SSM parameter that publishes the website's full domain.
      * Look up via {@link OpenHiWebsiteService.fullDomainFromConstruct}.
      */
     protected createFullDomainParameter(): void;
     /**
-     * Creates the StaticContent uploader. Always created so feature-branch
-     * deploys can publish content to their own sub-domain folder against the
-     * release-branch bucket.
-     *
-     * The destination bucket is resolved here so the construct never has to
-     * branch on release-vs-feature: on the release branch we pass the
-     * just-created {@link staticHosting} bucket directly (no SSM round-trip
-     * within a single stack); on every other branch we look up the bucket
-     * ARN published by the release-branch deploy, addressed against
-     * {@link OpenHiService.releaseBranchHash}.
+     * Creates the StaticContent uploader. Receives the resolved static-hosting
+     * bucket from the constructor — on the release-branch deploy this is the
+     * just-created {@link staticHosting} bucket (no SSM round-trip within a
+     * single stack); on every other deploy it is imported from the bucket ARN
+     * the release-branch deploy publishes to SSM, addressed against
+     * {@link OpenHiService.releaseBranchHash}. See
+     * {@link resolveStaticHostingBucket}.
      */
-    protected createStaticContent(): StaticContent;
+    protected createStaticContent(bucket: IBucket): StaticContent;
     /**
      * Returns an {@link IBucket} pointing at the static-hosting bucket the
-     * uploader writes to. On the release-branch deploy this is the bucket
+     * uploaders write to. On the release-branch deploy this is the bucket
      * just provisioned by {@link staticHosting}; on every other deploy it's
      * imported from the bucket ARN the release-branch deploy publishes to
      * SSM, addressed against {@link OpenHiService.releaseBranchHash}.
@@ -2918,5 +3073,5 @@ declare class RenameCascadeWorkflow extends Construct {
     constructor(scope: Construct, props: RenameCascadeWorkflowProps);
 }
 
-export { BRIDGED_STATUSES, CLOUDFORMATION_EVENT_SOURCE, CLOUDFORMATION_STACK_STATUS_CHANGE_DETAIL_TYPE, CONTROL_EVENT_BUS_NAME_ENV_VAR, ChildHostedZone, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DEMO_DATA_PLANE_FIXTURES, DEMO_PERIOD, DEMO_TENANT_SPECS, DEMO_URN_SYSTEM, DEV_USERS, DataEventBus, DataStoreHistoricalArchive, DataStorePostgresReplica, DiscoverableStringParameter, DynamoDbDataStore, OPENHI_REPO_TAG_KEY_ENV_VAR, OPENHI_RESOURCE_URN_SYSTEM, OPENHI_TAG_KEY_PREFIX_ENV_VAR, OPENHI_TAG_SUFFIX_BRANCH_NAME, OPENHI_TAG_SUFFIX_REPO_NAME, OPENHI_TAG_SUFFIX_SERVICE_TYPE, OPENHI_TAG_SUFFIX_STAGE_TYPE, OWNING_DELETE_CASCADE_CONSUMER_NAME, OWNING_DELETE_CASCADE_DEFAULT_CONCURRENCY, OWNING_DELETE_CASCADE_STUCK_THRESHOLD_MINUTES, OWNING_DELETE_OPS_EVENT_BUS_ENV_VAR, OpenHiApp, OpenHiAuthService, OpenHiDataService, OpenHiEnvironment, OpenHiGlobalService, OpenHiGraphqlService, OpenHiRestApiService, OpenHiService, OpenHiStage, OpenHiWebsiteService, OpsEventBus, OwningDeleteCascadeLambdas, OwningDeleteCascadeWorkflow, PLACEHOLDER_TENANT_ID, PLACEHOLDER_WORKSPACE_ID, PLATFORM_DEPLOY_BRIDGE_ACTOR_SYSTEM, PLATFORM_SCOPE_TENANT_ID, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PROVISION_DEFAULT_WORKSPACE_DETAIL_TYPE, PlatformDeployBridge, PlatformDeployBridgeLambda, PostAuthenticationLambda, PostConfirmationLambda, PreTokenGenerationLambda, ProvisionDefaultWorkspaceLambda, RENAME_CASCADE_CONSUMER_NAME, RENAME_CASCADE_DEFAULT_CONCURRENCY, RENAME_CASCADE_FAILED_THRESHOLD, RENAME_CASCADE_OPS_EVENT_BUS_ENV_VAR, RENAME_CASCADE_SLOW_THRESHOLD_SECONDS, REST_API_BASE_URL_SSM_NAME, RenameCascadeLambdas, RenameCascadeWorkflow, RootGraphqlApi, RootHostedZone, RootHttpApi, RootWildcardCertificate, SEED_DEMO_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_ACTOR_SYSTEM, SEED_SYSTEM_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR, SSM_PARAM_NAME_FULL_DOMAIN, STATIC_HOSTING_SERVICE_TYPE, SeedDemoDataLambda, SeedDemoDataWorkflow, SeedSystemDataLambda, SeedSystemDataWorkflow, StaticContent, StaticHosting, USER_ONBOARDING_EVENT_SOURCE, UserOnboardingWorkflow, WorkflowDedupConsumerNameInvalidError, WorkflowDedupTable, WorkflowDedupTableDuplicateError, buildFhirCurrentResourceChangeDetail, buildProvisionDefaultWorkspaceRequestedDetail, demoMembershipId, demoRoleAssignmentId, demoRolesForUserInTenant, demoScenarioIdentifier, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName, getWorkflowDedupTableName, openHiTagKey, openhiResourceIdentifier };
-export type { BridgedStatus, BuildParameterNameProps, CascadeChunkInput, CascadeFinalizeInput, CascadeFinalizeOutput, CascadeListInput, CascadeListOutput, ChildHostedZoneProps, CloudFormationStackStatusChangeDetail, DataEventBusOptions, DataStoreHistoricalArchiveProps, DataStorePostgresReplicaProps, DemoDevUser, DemoTenantSpec, DemoWorkspaceDataPlaneFixtures, DemoWorkspaceSpec, DiscoverableStringParameterProps, DynamoDbDataStoreProps, FhirCurrentResourceChangeDetail, GrantConsumerOptions, HostingMode, OpenHiAppProps, OpenHiAuthServiceProps, OpenHiDataServiceProps, OpenHiEnvironmentProps, OpenHiGlobalServiceProps, OpenHiGraphqlServiceProps, OpenHiRestApiServiceProps, OpenHiServiceProps, OpenHiServiceType, OpenHiStageProps, OpenHiWebsiteServiceProps, OwningDeleteCascadeLambdasProps, OwningDeleteCascadeWorkflowProps, PlatformDeployBridgeLambdaProps, PlatformDeployBridgeProps, PostConfirmationLambdaProps, PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambdaProps, ProvisionDefaultWorkspaceRequestedDetail, RenameCascadeChunkInput, RenameCascadeFinalizeInput, RenameCascadeFinalizeOutput, RenameCascadeLambdasProps, RenameCascadeListInput, RenameCascadeListOutput, RenameCascadeWorkflowProps, RootGraphqlApiProps, RootHttpApiProps, SeedDemoDataLambdaProps, SeedDemoDataWorkflowProps, SeedSystemDataLambdaProps, SeedSystemDataWorkflowProps, StaticContentProps, StaticHostingProps, UserOnboardingWorkflowProps, WorkflowDedupTableProps };
+export { BRIDGED_STATUSES, CLOUDFORMATION_EVENT_SOURCE, CLOUDFORMATION_STACK_STATUS_CHANGE_DETAIL_TYPE, CONTROL_EVENT_BUS_NAME_ENV_VAR, ChildHostedZone, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, ControlEventBus, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DEMO_DATA_PLANE_FIXTURES, DEMO_PERIOD, DEMO_TENANT_SPECS, DEMO_URN_SYSTEM, DEV_USERS, DataEventBus, DataStoreHistoricalArchive, DataStorePostgresReplica, DiscoverableStringParameter, DynamoDbDataStore, OPENHI_REPO_TAG_KEY_ENV_VAR, OPENHI_RESOURCE_URN_SYSTEM, OPENHI_TAG_KEY_PREFIX_ENV_VAR, OPENHI_TAG_SUFFIX_BRANCH_NAME, OPENHI_TAG_SUFFIX_REPO_NAME, OPENHI_TAG_SUFFIX_SERVICE_TYPE, OPENHI_TAG_SUFFIX_STAGE_TYPE, OWNING_DELETE_CASCADE_CONSUMER_NAME, OWNING_DELETE_CASCADE_DEFAULT_CONCURRENCY, OWNING_DELETE_CASCADE_STUCK_THRESHOLD_MINUTES, OWNING_DELETE_OPS_EVENT_BUS_ENV_VAR, OpenHiApp, OpenHiAuthService, OpenHiDataService, OpenHiEnvironment, OpenHiGlobalService, OpenHiGraphqlService, OpenHiRestApiService, OpenHiService, OpenHiStage, OpenHiWebsiteService, OpsEventBus, OwningDeleteCascadeLambdas, OwningDeleteCascadeWorkflow, PLACEHOLDER_TENANT_ID, PLACEHOLDER_WORKSPACE_ID, PLATFORM_DEPLOY_BRIDGE_ACTOR_SYSTEM, PLATFORM_SCOPE_TENANT_ID, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PROVISION_DEFAULT_WORKSPACE_DETAIL_TYPE, PlatformDeployBridge, PlatformDeployBridgeLambda, PostAuthenticationLambda, PostConfirmationLambda, PreTokenGenerationLambda, ProvisionDefaultWorkspaceLambda, RENAME_CASCADE_CONSUMER_NAME, RENAME_CASCADE_DEFAULT_CONCURRENCY, RENAME_CASCADE_FAILED_THRESHOLD, RENAME_CASCADE_OPS_EVENT_BUS_ENV_VAR, RENAME_CASCADE_SLOW_THRESHOLD_SECONDS, REST_API_BASE_URL_SSM_NAME, REST_API_DOMAIN_NAME_SSM_NAME, RenameCascadeLambdas, RenameCascadeWorkflow, RootGraphqlApi, RootHostedZone, RootHttpApi, RootWildcardCertificate, SEED_DEMO_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_ACTOR_SYSTEM, SEED_SYSTEM_DATA_CONSUMER_NAME, SEED_SYSTEM_DATA_CONTROL_BUS_ENV_VAR, SSM_PARAM_NAME_FULL_DOMAIN, STATIC_HOSTING_SERVICE_TYPE, SeedDemoDataLambda, SeedDemoDataWorkflow, SeedSystemDataLambda, SeedSystemDataWorkflow, StaticContent, StaticHosting, USER_ONBOARDING_EVENT_SOURCE, UserOnboardingWorkflow, WorkflowDedupConsumerNameInvalidError, WorkflowDedupTable, WorkflowDedupTableDuplicateError, buildFhirCurrentResourceChangeDetail, buildProvisionDefaultWorkspaceRequestedDetail, computeBranchHash, demoMembershipId, demoRoleAssignmentId, demoRolesForUserInTenant, demoScenarioIdentifier, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName, getWorkflowDedupTableName, openHiTagKey, openhiResourceIdentifier };
+export type { BridgedStatus, BuildParameterNameProps, CascadeChunkInput, CascadeFinalizeInput, CascadeFinalizeOutput, CascadeListInput, CascadeListOutput, ChildHostedZoneProps, CloudFormationStackStatusChangeDetail, ComputeBranchHashOptions, DataEventBusOptions, DataStoreHistoricalArchiveProps, DataStorePostgresReplicaProps, DemoDevUser, DemoTenantSpec, DemoWorkspaceDataPlaneFixtures, DemoWorkspaceSpec, DiscoverableStringParameterProps, DynamoDbDataStoreProps, FhirCurrentResourceChangeDetail, GrantConsumerOptions, HostingMode, OpenHiAppProps, OpenHiAuthServiceProps, OpenHiDataServiceProps, OpenHiEnvironmentProps, OpenHiGlobalServiceProps, OpenHiGraphqlServiceProps, OpenHiRestApiRuntimeConfig, OpenHiRestApiServiceProps, OpenHiServiceProps, OpenHiServiceType, OpenHiStageProps, OpenHiWebsiteServiceProps, OwningDeleteCascadeLambdasProps, OwningDeleteCascadeWorkflowProps, PlatformDeployBridgeLambdaProps, PlatformDeployBridgeProps, PostConfirmationLambdaProps, PreTokenGenerationLambdaProps, ProvisionDefaultWorkspaceLambdaProps, ProvisionDefaultWorkspaceRequestedDetail, RenameCascadeChunkInput, RenameCascadeFinalizeInput, RenameCascadeFinalizeOutput, RenameCascadeLambdasProps, RenameCascadeListInput, RenameCascadeListOutput, RenameCascadeWorkflowProps, RootGraphqlApiProps, RootHttpApiProps, SeedDemoDataLambdaProps, SeedDemoDataWorkflowProps, SeedSystemDataLambdaProps, SeedSystemDataWorkflowProps, StaticContentProps, StaticHostingProps, UserOnboardingWorkflowProps, WorkflowDedupTableProps };