@openhi/constructs 0.0.105 → 0.0.107

package/lib/seed-demo-data.handler.d.mts

@@ -0,0 +1,107 @@
+import { WorkflowDedupClient } from '@openhi/workflows';
+import { EventBridgeEvent } from 'aws-lambda';
+import { d as DemoDevUser } from './events-DPodvl07.mjs';
+import { O as OpenHiContext } from './openhi-context-CaBH8SFo.mjs';
+import '@openhi/types';
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/seed-demo-data/seed-demo-data-handler.md
+ *
+ * EventBridge workflow handler invoked once per platform-deploy event
+ * on the control event bus. Pre-flight verifies that
+ * `seed-system-data` has already seeded the canonical Role records,
+ * then idempotently re-asserts the demo-data graph: the placeholder
+ * Tenant + Workspace, the three demo tenants + their workspaces, and
+ * for each entry in {@link DEV_USERS} a Cognito user, a DynamoDB User,
+ * 4 Memberships, 4 `tenant-admin` RoleAssignments, plus 1
+ * platform-scoped `system-admin` RoleAssignment.
+ */
+type SeedDemoDataEvent = EventBridgeEvent<"platform.system-data-seeded.v1", unknown>;
+/** Env var the lambda construct injects with the Cognito User Pool ID. */
+declare const SEED_DEMO_DATA_USER_POOL_ID_ENV_VAR = "SEED_DEMO_DATA_USER_POOL_ID";
+/** Inputs the handler needs to provision Cognito users for every dev. */
+interface CognitoProvisioner {
+    /**
+     * Ensure a Cognito user exists for `email`. Returns the user's
+     * `sub`. Implementations MUST be idempotent: a second invocation
+     * for the same email returns the existing user's sub without
+     * resetting its password or touching any attribute.
+     */
+    readonly ensureUser: (email: string) => Promise<string>;
+}
+/**
+ * Dependency seam for tests. The factory mirrors the production
+ * arrangement: a real DynamoDB client + the real `workflowDedupClient`
+ * factory bound to the `OPENHI_WORKFLOW_DEDUP_TABLE_NAME` env var the
+ * construct injects via `grantConsumer`.
+ */
+interface SeedDemoDataDependencies {
+    readonly dedupClient: WorkflowDedupClient;
+    /**
+     * Reads every id in `PLATFORM_ROLE_IDS`. Throws when any Role
+     * record is missing — that means `seed-system-data` has not yet
+     * run on this environment, and emitting demo RoleAssignments that
+     * reference non-existent Roles would produce orphaned records.
+     */
+    readonly verifyRoles: () => Promise<void>;
+    /**
+     * Upserts every Tenant + Workspace in {@link DEMO_TENANT_SPECS},
+     * plus per-dev-user Cognito users, DynamoDB User records,
+     * Memberships, and RoleAssignments.
+     */
+    readonly seedDemoGraph: (params: {
+        readonly baseContext: OpenHiContext;
+        readonly devUsers: ReadonlyArray<DemoDevUser>;
+        readonly cognito: CognitoProvisioner;
+    }) => Promise<void>;
+    /** Cognito provisioner threaded into `seedDemoGraph`. */
+    readonly cognito: CognitoProvisioner;
+}
+/**
+ * Upsert the full demo-data graph. Walks each spec in
+ * {@link DEMO_TENANT_SPECS}: Tenant → Workspaces. Then per dev user:
+ * Cognito user → DynamoDB User → per-tenant Membership +
+ * `tenant-admin` RoleAssignment → platform-scoped `system-admin`
+ * RoleAssignment. Every put is keyed by a deterministic stable id so
+ * re-runs after dedup-TTL expiry upsert the same records.
+ *
+ * Exported so the seeder test file can exercise it directly against
+ * a mocked DynamoControlService; the production handler reaches it
+ * through {@link SeedDemoDataDependencies.seedDemoGraph}.
+ */
+declare const seedDemoGraph: (params: {
+    baseContext: OpenHiContext;
+    devUsers: ReadonlyArray<DemoDevUser>;
+    cognito: CognitoProvisioner;
+}) => Promise<void>;
+/**
+ * Test-visible orchestrator. The production `handler` calls this with
+ * real dependencies and the hardcoded {@link DEV_USERS} list; unit
+ * tests inject fakes and pass the dev-user list directly.
+ */
+declare const runSeedDemoData: (event: SeedDemoDataEvent, deps: SeedDemoDataDependencies, devUsers: ReadonlyArray<DemoDevUser>) => Promise<void>;
+/**
+ * Deterministic password derived from the user's email. Re-running
+ * the algorithm with the same email reproduces the password, so devs
+ * can recover their own credentials from the docs page without the
+ * workflow ever surfacing them. The shape satisfies the default
+ * Cognito password policy (≥8 chars, upper + lower + number + symbol).
+ */
+declare const devPasswordForEmail: (email: string) => string;
+/**
+ * Production Cognito provisioner backed by the AWS SDK. Reads the
+ * user-pool id from the env var the lambda construct injects.
+ *
+ * Idempotency contract:
+ *   - On first invocation, calls `AdminCreateUser` (with
+ *     `MessageAction: SUPPRESS` so no invitation email fires) then
+ *     `AdminSetUserPassword` (permanent). Returns the new user's sub.
+ *   - On subsequent invocations, `AdminCreateUser` throws
+ *     `UsernameExistsException`; the provisioner catches it, calls
+ *     `AdminGetUser` to read the existing user's sub, and returns
+ *     **without** touching the password or any attribute.
+ */
+declare const productionCognitoProvisioner: () => CognitoProvisioner;
+declare const handler: (event: SeedDemoDataEvent) => Promise<void>;
+
+export { type CognitoProvisioner, SEED_DEMO_DATA_USER_POOL_ID_ENV_VAR, type SeedDemoDataDependencies, devPasswordForEmail, handler, productionCognitoProvisioner, runSeedDemoData, seedDemoGraph };

package/lib/seed-demo-data.handler.d.ts

@@ -0,0 +1,107 @@
+import { WorkflowDedupClient } from '@openhi/workflows';
+import { EventBridgeEvent } from 'aws-lambda';
+import { d as DemoDevUser } from './events-DPodvl07.js';
+import { O as OpenHiContext } from './openhi-context-CaBH8SFo.js';
+import '@openhi/types';
+
+/**
+ * @see sites/www-docs/content/packages/@openhi/constructs/workflows/control-plane/seed-demo-data/seed-demo-data-handler.md
+ *
+ * EventBridge workflow handler invoked once per platform-deploy event
+ * on the control event bus. Pre-flight verifies that
+ * `seed-system-data` has already seeded the canonical Role records,
+ * then idempotently re-asserts the demo-data graph: the placeholder
+ * Tenant + Workspace, the three demo tenants + their workspaces, and
+ * for each entry in {@link DEV_USERS} a Cognito user, a DynamoDB User,
+ * 4 Memberships, 4 `tenant-admin` RoleAssignments, plus 1
+ * platform-scoped `system-admin` RoleAssignment.
+ */
+type SeedDemoDataEvent = EventBridgeEvent<"platform.system-data-seeded.v1", unknown>;
+/** Env var the lambda construct injects with the Cognito User Pool ID. */
+declare const SEED_DEMO_DATA_USER_POOL_ID_ENV_VAR = "SEED_DEMO_DATA_USER_POOL_ID";
+/** Inputs the handler needs to provision Cognito users for every dev. */
+interface CognitoProvisioner {
+    /**
+     * Ensure a Cognito user exists for `email`. Returns the user's
+     * `sub`. Implementations MUST be idempotent: a second invocation
+     * for the same email returns the existing user's sub without
+     * resetting its password or touching any attribute.
+     */
+    readonly ensureUser: (email: string) => Promise<string>;
+}
+/**
+ * Dependency seam for tests. The factory mirrors the production
+ * arrangement: a real DynamoDB client + the real `workflowDedupClient`
+ * factory bound to the `OPENHI_WORKFLOW_DEDUP_TABLE_NAME` env var the
+ * construct injects via `grantConsumer`.
+ */
+interface SeedDemoDataDependencies {
+    readonly dedupClient: WorkflowDedupClient;
+    /**
+     * Reads every id in `PLATFORM_ROLE_IDS`. Throws when any Role
+     * record is missing — that means `seed-system-data` has not yet
+     * run on this environment, and emitting demo RoleAssignments that
+     * reference non-existent Roles would produce orphaned records.
+     */
+    readonly verifyRoles: () => Promise<void>;
+    /**
+     * Upserts every Tenant + Workspace in {@link DEMO_TENANT_SPECS},
+     * plus per-dev-user Cognito users, DynamoDB User records,
+     * Memberships, and RoleAssignments.
+     */
+    readonly seedDemoGraph: (params: {
+        readonly baseContext: OpenHiContext;
+        readonly devUsers: ReadonlyArray<DemoDevUser>;
+        readonly cognito: CognitoProvisioner;
+    }) => Promise<void>;
+    /** Cognito provisioner threaded into `seedDemoGraph`. */
+    readonly cognito: CognitoProvisioner;
+}
+/**
+ * Upsert the full demo-data graph. Walks each spec in
+ * {@link DEMO_TENANT_SPECS}: Tenant → Workspaces. Then per dev user:
+ * Cognito user → DynamoDB User → per-tenant Membership +
+ * `tenant-admin` RoleAssignment → platform-scoped `system-admin`
+ * RoleAssignment. Every put is keyed by a deterministic stable id so
+ * re-runs after dedup-TTL expiry upsert the same records.
+ *
+ * Exported so the seeder test file can exercise it directly against
+ * a mocked DynamoControlService; the production handler reaches it
+ * through {@link SeedDemoDataDependencies.seedDemoGraph}.
+ */
+declare const seedDemoGraph: (params: {
+    baseContext: OpenHiContext;
+    devUsers: ReadonlyArray<DemoDevUser>;
+    cognito: CognitoProvisioner;
+}) => Promise<void>;
+/**
+ * Test-visible orchestrator. The production `handler` calls this with
+ * real dependencies and the hardcoded {@link DEV_USERS} list; unit
+ * tests inject fakes and pass the dev-user list directly.
+ */
+declare const runSeedDemoData: (event: SeedDemoDataEvent, deps: SeedDemoDataDependencies, devUsers: ReadonlyArray<DemoDevUser>) => Promise<void>;
+/**
+ * Deterministic password derived from the user's email. Re-running
+ * the algorithm with the same email reproduces the password, so devs
+ * can recover their own credentials from the docs page without the
+ * workflow ever surfacing them. The shape satisfies the default
+ * Cognito password policy (≥8 chars, upper + lower + number + symbol).
+ */
+declare const devPasswordForEmail: (email: string) => string;
+/**
+ * Production Cognito provisioner backed by the AWS SDK. Reads the
+ * user-pool id from the env var the lambda construct injects.
+ *
+ * Idempotency contract:
+ *   - On first invocation, calls `AdminCreateUser` (with
+ *     `MessageAction: SUPPRESS` so no invitation email fires) then
+ *     `AdminSetUserPassword` (permanent). Returns the new user's sub.
+ *   - On subsequent invocations, `AdminCreateUser` throws
+ *     `UsernameExistsException`; the provisioner catches it, calls
+ *     `AdminGetUser` to read the existing user's sub, and returns
+ *     **without** touching the password or any attribute.
+ */
+declare const productionCognitoProvisioner: () => CognitoProvisioner;
+declare const handler: (event: SeedDemoDataEvent) => Promise<void>;
+
+export { type CognitoProvisioner, SEED_DEMO_DATA_USER_POOL_ID_ENV_VAR, type SeedDemoDataDependencies, devPasswordForEmail, handler, productionCognitoProvisioner, runSeedDemoData, seedDemoGraph };