@openhi/constructs 0.0.85 → 0.0.87

package/lib/index.d.ts

@@ -3,7 +3,7 @@ import { Construct, IConstruct } from 'constructs';
 import { ICertificate, Certificate, CertificateProps } from 'aws-cdk-lib/aws-certificatemanager';
 import { IHttpApi, HttpApiProps, HttpApi, DomainName } from 'aws-cdk-lib/aws-apigatewayv2';
 import { IGraphqlApi, GraphqlApi, GraphqlApiProps } from 'aws-cdk-lib/aws-appsync';
-import { UserPool, UserPoolProps, UserPoolClient, UserPoolClientProps, UserPoolDomain, UserPoolDomainProps, IUserPool, IUserPoolClient, IUserPoolDomain } from 'aws-cdk-lib/aws-cognito';
+import { UserPoolClient, UserPoolClientProps, IUserPool, UserPool, UserPoolProps, UserPoolDomain, UserPoolDomainProps, IUserPoolClient, IUserPoolDomain } from 'aws-cdk-lib/aws-cognito';
 import { Key, KeyProps, IKey } from 'aws-cdk-lib/aws-kms';
 import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
 import { AttributeValue } from '@aws-sdk/client-dynamodb';
@@ -14,6 +14,8 @@ import * as kinesisfirehose from 'aws-cdk-lib/aws-kinesisfirehose';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import { IBucket, BucketProps } from 'aws-cdk-lib/aws-s3';
 import { Table, TableProps, ITable } from 'aws-cdk-lib/aws-dynamodb';
+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 } from 'aws-cdk-lib/aws-cloudfront';
@@ -482,6 +484,47 @@ declare class RootGraphqlApi extends GraphqlApi {
     constructor(scope: Construct, props?: Omit<RootGraphqlApiProps, "name">);
 }
 
+interface CognitoFixtureSeederClientProps extends Partial<Omit<UserPoolClientProps, "userPool" | "generateSecret">> {
+    readonly userPool: IUserPool;
+}
+/**
+ * Dedicated Cognito app client for the OpenHI fixture-seeder CLI
+ * (`@openhi/seed-fixtures`).
+ *
+ * Why a dedicated client (vs reusing the SPA client):
+ * - Tightly scoped: only the seeder consumes tokens issued here, so an
+ *   audit trail of seeder activity is cleanly separable.
+ * - Decoupled from the SPA client's OAuth flows — no risk of breaking
+ *   web-app sign-in by tweaking auth-flow settings here.
+ * - Stage-conditional creation upstream (only provisioned in non-prod
+ *   environments) means prod stacks never carry a code path that could
+ *   issue a fixture-seeder token in the first place.
+ *
+ * Why USER_PASSWORD_AUTH (vs M2M client-credentials):
+ * - Cognito's M2M tier has a per-app-client monthly fee plus per-token
+ *   activity charges. For sporadic non-prod fixture runs the per-client
+ *   fee dominates the bill, especially if every dev branch spins up
+ *   its own auth stack.
+ * - USER_PASSWORD_AUTH against a service `fixture-seeder` user keeps
+ *   the cost in MAU territory (free under the 50K MAU tier).
+ * - Tradeoff: passwords need rotation and the service user must be
+ *   provisioned per non-prod environment (manual or scripted post-deploy).
+ *
+ * No client secret (`generateSecret: false`): USER_PASSWORD_AUTH
+ * authenticates with the password directly; a secret would just add
+ * another credential to manage without strengthening anything.
+ */
+declare class CognitoFixtureSeederClient extends UserPoolClient {
+    /**
+     * SSM parameter name suffix used to publish this client's ID for
+     * cross-stack lookups. Built into a full parameter name via
+     * `buildParameterName` with `serviceType` AUTH (since the auth stack
+     * owns this resource).
+     */
+    static readonly SSM_PARAM_NAME = "COGNITO_FIXTURE_SEEDER_CLIENT";
+    constructor(scope: Construct, props: CognitoFixtureSeederClientProps);
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/components/cognito/cognito-user-pool.md
  */
@@ -526,6 +569,14 @@ declare class CognitoUserPoolKmsKey extends Key {
     constructor(scope: Construct, props?: KeyProps);
 }
 
+/**
+ * Lambda used as Cognito Post Authentication trigger.
+ */
+declare class PostAuthenticationLambda extends Construct {
+    readonly lambda: NodejsFunction;
+    constructor(scope: Construct);
+}
+
 /**
  * Lambda used as Cognito Pre Token Generation trigger.
  */
@@ -619,13 +670,25 @@ interface DynamoDbDataStoreProps extends Omit<TableProps, "tableName" | "removal
     readonly removalPolicy?: RemovalPolicy;
 }
 /**
- * DynamoDB table implementing the single-table design for app data (e.g. FHIR
- * resources and configuration).
+ * DynamoDB table implementing the single-table design for app data (FHIR
+ * resources data plane and platform control plane), per planning ADR-011 and
+ * DR-004.
  *
  * @see {@link https://github.com/codedrifters/openhi/blob/main/sites/www-docs/content/architecture/dynamodb-single-table-design.md | DynamoDB Single-Table Design}
  *
  * Primary key: PK (String), SK (String).
- * GSIs: GSI1 (reverse reference), GSI2 (identifier lookup), GSI3 (facility ops), GSI4 (resource type list).
+ *
+ * GSIs:
+ * - **GSI1 — Unified Sharded List** (`GSI1PK`/`GSI1SK`, INCLUDE projection per
+ *   DR-004). Primary list/lookup index for both data-plane FHIR resources and
+ *   control-plane entities (User, Tenant, Workspace, Membership, Role,
+ *   RoleAssignment, Configuration). PK shape:
+ *   `TID#<tid>#WID#<wid>#RT#<Type>#SHARD#<n>` with 4 shards
+ *   (`n = hash(id) mod 4`). SK shape per `extractSortKey`: labeled types use
+ *   `<normalizedLabel>#<id>`; unlabeled use `<ISO-8601 lastUpdated>#<id>`.
+ * - **GSI2 — Sub-Lookup** (`GSI2PK`/`GSI2SK`, INCLUDE projection). Resolves
+ *   `UserEntity` from a Cognito `sub` for the Pre Token Generation Lambda.
+ *   PK shape: `USER#SUB#<cognitoSub>`. SK shape: `CURRENT`.
  *
  * For historical archive to S3, pass `kinesisStream` and `stream` (e.g.
  * `StreamViewType.NEW_AND_OLD_IMAGES`) on the table props per ADR 2026-03-11-02.
@@ -664,6 +727,111 @@ declare class OpsEventBus extends EventBus {
     constructor(scope: Construct, props?: EventBusProps);
 }
 
+/**
+ * SSM parameter names that publish the Postgres replica's coordinates so other
+ * stacks (notably the REST API stack) can discover them without a direct CDK
+ * cross-stack reference. The schema name is intentionally NOT published — it
+ * is a deterministic function of `branchHash` and consumers compute it locally
+ * via {@link getPostgresReplicaSchemaName}.
+ */
+declare const POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME = "POSTGRES_REPLICA_CLUSTER_ARN";
+declare const POSTGRES_REPLICA_SECRET_ARN_SSM_NAME = "POSTGRES_REPLICA_SECRET_ARN";
+declare const POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME = "POSTGRES_REPLICA_DATABASE_NAME";
+/**
+ * Derive the per-branch Postgres schema name from a branch hash. The `b_`
+ * prefix guarantees a leading letter (Postgres identifier rule). Branch hashes
+ * are 6 hex chars from {@link OpenHiService.branchHash} so the resulting
+ * `b_xxxxxx` is well within the 63-byte identifier limit.
+ */
+declare function getPostgresReplicaSchemaName(branchHash: string): string;
+interface DataStorePostgresReplicaProps {
+    /**
+     * Kinesis stream that receives DynamoDB item-level changes (the same stream
+     * that backs {@link DataStoreHistoricalArchive}). The replication Lambda is
+     * registered as a parallel consumer.
+     */
+    readonly kinesisStream: kinesis.IStream;
+    /**
+     * Removal policy for the cluster, secret, and dependent resources.
+     */
+    readonly removalPolicy: RemovalPolicy;
+    /**
+     * Short hash unique to the stack — used in the cluster identifier.
+     */
+    readonly stackHash: string;
+    /**
+     * Short hash unique to the branch — used to derive the per-branch schema
+     * name (`b_<branchHash>`) inside the Postgres database.
+     */
+    readonly branchHash: string;
+    /**
+     * Optional VPC override. If absent, the construct creates a minimal isolated
+     * VPC (2 AZs, no NAT gateways) just for the cluster and replication Lambda.
+     */
+    readonly vpc?: ec2.IVpc;
+    /**
+     * Optional database name override.
+     * @default "openhi"
+     */
+    readonly databaseName?: string;
+    /**
+     * Aurora Serverless v2 minimum capacity in ACUs. Defaults to 1 so the
+     * writer stays warm — avoids the ~10–20s scale-up wait that a cold
+     * (0 ACU) cluster imposes on the next request. Set explicitly to 0 to
+     * opt back into scale-to-zero if idle cost becomes the dominant concern.
+     */
+    readonly minCapacity?: number;
+    /**
+     * Aurora Serverless v2 maximum capacity in ACUs. Defaults to 2 — adequate
+     * for the PoC's replication-only workload.
+     */
+    readonly maxCapacity?: number;
+}
+/**
+ * DynamoDB change stream → Postgres replication tier (ADR 2026-04-17-01,
+ * phase 1). Provisions an Aurora Serverless v2 PostgreSQL cluster and a
+ * Lambda consumer on the existing change-stream that projects each current
+ * FHIR resource into a JSONB `resources` table under a per-branch schema.
+ *
+ * Phase 1 is replication-only; query routing and SearchParameter-specific
+ * indexes are intentionally deferred. Per-branch *clusters* (rather than the
+ * shared cluster suggested by the ADR) are an explicit PoC simplification —
+ * see the ADR's "Operational notes" section for the long-term direction.
+ *
+ * @see sites/www-docs/content/architecture/adr/2026-04-17-01-ad-hoc-query-support-fhir-api.md
+ */
+declare class DataStorePostgresReplica extends Construct {
+    /**
+     * Resolve the cluster ARN published by an upstream {@link DataStorePostgresReplica}.
+     * Use from any stack that needs to grant `rds-data:ExecuteStatement` against
+     * the cluster.
+     */
+    static clusterArnFromConstruct(scope: Construct): string;
+    /**
+     * Resolve the credentials secret ARN published by an upstream
+     * {@link DataStorePostgresReplica}. Use from any stack that needs to grant
+     * `secretsmanager:GetSecretValue` against the secret.
+     */
+    static secretArnFromConstruct(scope: Construct): string;
+    /**
+     * Resolve the database name published by an upstream
+     * {@link DataStorePostgresReplica}.
+     */
+    static databaseNameFromConstruct(scope: Construct): string;
+    readonly vpc: ec2.IVpc;
+    readonly cluster: rds.DatabaseCluster;
+    readonly replicationFunction: NodejsFunction;
+    readonly databaseName: string;
+    readonly schemaName: string;
+    constructor(scope: Construct, id: string, props: DataStorePostgresReplicaProps);
+    /**
+     * Publishes the cluster ARN, secret ARN, and database name as discoverable
+     * SSM parameters so the REST API stack (and any future read-side consumer)
+     * can wire RDS Data API access without a direct CDK cross-stack reference.
+     */
+    private publishCoordinatesToSsm;
+}
+
 /**
  * @see sites/www-docs/content/packages/@openhi/constructs/components/route-53/child-hosted-zone.md
  */
@@ -842,6 +1010,17 @@ declare class OpenHiAuthService extends OpenHiService {
      * Returns an IUserPoolClient by looking up the Auth stack's User Pool Client ID from SSM.
      */
     static userPoolClientFromConstruct(scope: Construct): IUserPoolClient;
+    /**
+     * Returns the dedicated fixture-seeder IUserPoolClient by looking up
+     * its ID from SSM. Only non-prod auth stacks publish this parameter
+     * (per the conditional in {@link createFixtureSeederClient}); calling
+     * this against a prod-deployed stack will fail at lookup time.
+     *
+     * Consumed by `OpenHiRestApiService` (in non-prod) so the authorizer
+     * accepts tokens issued by this client, and by the seed-fixtures CLI
+     * to drive USER_PASSWORD_AUTH against this client's ID.
+     */
+    static fixtureSeederClientFromConstruct(scope: Construct): IUserPoolClient;
     /**
      * Returns an IUserPoolDomain by looking up the Auth stack's User Pool Domain from SSM.
      */
@@ -855,9 +1034,16 @@ declare class OpenHiAuthService extends OpenHiService {
     props: OpenHiAuthServiceProps;
     readonly userPoolKmsKey: IKey;
     readonly preTokenGenerationLambda: IFunction;
+    readonly postAuthenticationLambda: IFunction;
     readonly userPool: IUserPool;
     readonly userPoolClient: IUserPoolClient;
     readonly userPoolDomain: IUserPoolDomain;
+    /**
+     * Dedicated USER_PASSWORD_AUTH client for the seed-fixtures CLI.
+     * Only created in non-prod environments (see
+     * {@link createFixtureSeederClient}). `undefined` in prod.
+     */
+    readonly fixtureSeederClient?: IUserPoolClient;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiAuthServiceProps);
     /**
      * Creates the KMS key for the Cognito User Pool and exports its ARN to SSM.
@@ -870,18 +1056,50 @@ declare class OpenHiAuthService extends OpenHiService {
      * openhi_* claims to the access token only; trigger version V2_0 may be required.
      */
     protected createPreTokenGenerationLambda(): IFunction;
+    /**
+     * Creates the Post Authentication Lambda (Cognito trigger). Calls
+     * AdminUserGlobalSignOut on every sign-in to enforce single-device-per-user
+     * sessions per ADR 2026-03-17-01.
+     */
+    protected createPostAuthenticationLambda(): IFunction;
     /**
      * Creates the Cognito User Pool and exports its ID to SSM.
      * Look up via {@link OpenHiAuthService.userPoolFromConstruct}.
      * Override to customize.
      */
     protected createUserPool(): IUserPool;
+    /**
+     * Grants the Post Authentication Lambda permission to call
+     * `cognito-idp:AdminUserGlobalSignOut`.
+     *
+     * Scoped via `Stack.of(this).formatArn` rather than `userPool.userPoolArn`
+     * because the User Pool registers this Lambda as a Post Authentication
+     * trigger, creating the cycle:
+     *   userPool → lambda (trigger ARN) → role policy → userPool ARN.
+     * Using `formatArn` avoids referencing the User Pool resource directly
+     * while still scoping to user pools in this account+region. The Lambda
+     * is invoked only by Cognito with a Cognito-provided `event.userPoolId`,
+     * so the runtime target is constrained by the trigger contract.
+     */
+    protected grantPostAuthenticationPermissions(): void;
     /**
      * Creates the User Pool Client and exports its ID to SSM (AUTH service type).
      * Look up via {@link OpenHiAuthService.userPoolClientFromConstruct}.
      * Override to customize.
      */
     protected createUserPoolClient(): IUserPoolClient;
+    /**
+     * Creates the dedicated USER_PASSWORD_AUTH app client for the
+     * `@openhi/seed-fixtures` CLI, **only** in non-prod environments.
+     * Returns `undefined` when this stack is being deployed to a prod
+     * stage so the prod auth stack carries no fixture-seeder code path.
+     *
+     * Operator post-deploy: create a `fixture-seeder` Cognito user with
+     * a service password (manually via console or scripted with
+     * `aws cognito-idp admin-create-user`); the CLI consumes those creds
+     * via env vars to drive `InitiateAuth`.
+     */
+    protected createFixtureSeederClient(): IUserPoolClient | undefined;
     /**
      * Creates the User Pool Domain (Cognito hosted UI) and exports domain name to SSM.
      * Look up via {@link OpenHiAuthService.userPoolDomainFromConstruct}.
@@ -1078,6 +1296,13 @@ declare class OpenHiDataService extends OpenHiService {
      * notifications for current FHIR resources (ADRs 2026-03-11-02, 2026-03-02-01).
      */
     readonly dataStoreHistoricalArchive: DataStoreHistoricalArchive;
+    /**
+     * Postgres replication tier (ADR 2026-04-17-01, phase 1). A second consumer
+     * on the change stream that projects current FHIR resources into a JSONB
+     * `resources` table on Aurora Serverless v2. Phase 1 is replication-only;
+     * the read path is not wired up yet.
+     */
+    readonly dataStorePostgresReplica: DataStorePostgresReplica;
     constructor(ohEnv: OpenHiEnvironment, props?: OpenHiDataServiceProps);
     /**
      * Creates the data event bus.
@@ -1118,5 +1343,5 @@ declare class OpenHiGraphqlService extends OpenHiService {
     protected createRootGraphqlApi(): RootGraphqlApi;
 }
 
-export { ChildHostedZone, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DataEventBus, DataStoreHistoricalArchive, DiscoverableStringParameter, DynamoDbDataStore, OpenHiApp, OpenHiAuthService, OpenHiDataService, OpenHiEnvironment, OpenHiGlobalService, OpenHiGraphqlService, OpenHiRestApiService, OpenHiService, OpenHiStage, OpsEventBus, PreTokenGenerationLambda, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, RootHostedZone, RootHttpApi, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName };
-export type { BuildParameterNameProps, ChildHostedZoneProps, DataStoreHistoricalArchiveProps, DiscoverableStringParameterProps, DynamoDbDataStoreProps, FhirCurrentResourceChangeDetail, OpenHiAppProps, OpenHiAuthServiceProps, OpenHiDataServiceProps, OpenHiEnvironmentProps, OpenHiGlobalServiceProps, OpenHiGraphqlServiceProps, OpenHiRestApiServiceProps, OpenHiServiceProps, OpenHiServiceType, OpenHiStageProps, RootGraphqlApiProps, RootHttpApiProps, StaticHostingProps };
+export { ChildHostedZone, CognitoFixtureSeederClient, CognitoUserPool, CognitoUserPoolClient, CognitoUserPoolDomain, CognitoUserPoolKmsKey, DATA_STORE_CHANGE_DETAIL_MAX_UTF8_BYTES, DATA_STORE_CHANGE_DETAIL_TYPE, DATA_STORE_CHANGE_EVENT_SOURCE, DataEventBus, DataStoreHistoricalArchive, DataStorePostgresReplica, DiscoverableStringParameter, DynamoDbDataStore, OpenHiApp, OpenHiAuthService, OpenHiDataService, OpenHiEnvironment, OpenHiGlobalService, OpenHiGraphqlService, OpenHiRestApiService, OpenHiService, OpenHiStage, OpsEventBus, POSTGRES_REPLICA_CLUSTER_ARN_SSM_NAME, POSTGRES_REPLICA_DATABASE_NAME_SSM_NAME, POSTGRES_REPLICA_SECRET_ARN_SSM_NAME, PostAuthenticationLambda, PreTokenGenerationLambda, REST_API_BASE_URL_SSM_NAME, RootGraphqlApi, RootHostedZone, RootHttpApi, RootWildcardCertificate, STATIC_HOSTING_SERVICE_TYPE, StaticHosting, buildFhirCurrentResourceChangeDetail, getDynamoDbDataStoreTableName, getPostgresReplicaSchemaName };
+export type { BuildParameterNameProps, ChildHostedZoneProps, CognitoFixtureSeederClientProps, DataStoreHistoricalArchiveProps, DataStorePostgresReplicaProps, DiscoverableStringParameterProps, DynamoDbDataStoreProps, FhirCurrentResourceChangeDetail, OpenHiAppProps, OpenHiAuthServiceProps, OpenHiDataServiceProps, OpenHiEnvironmentProps, OpenHiGlobalServiceProps, OpenHiGraphqlServiceProps, OpenHiRestApiServiceProps, OpenHiServiceProps, OpenHiServiceType, OpenHiStageProps, RootGraphqlApiProps, RootHttpApiProps, StaticHostingProps };