@openhi/constructs 0.0.151 → 0.0.153

package/lib/rest-api-lambda.handler.mjs

@@ -23,7 +23,7 @@ import {
   createTenantOperation,
   createWorkspaceOperation,
   extractDenormalizedReferenceDisplay
-} from "./chunk-AWYZJFPL.mjs";
+} from "./chunk-CFJDATDK.mjs";
 import {
   buildMembershipUserProjectionItem,
   buildMembershipWorkspaceProjectionItem,

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

@@ -1,6 +1,6 @@
 import { WorkflowDedupClient } from '@openhi/workflows';
 import { EventBridgeEvent } from 'aws-lambda';
-import { d as DemoDevUser } from './events-CMG8xanm.mjs';
+import { d as DemoDevUser } from './events-DTgo2dcW.mjs';
 import { O as OpenHiContext } from './openhi-context-CaBH8SFo.mjs';
 import '@openhi/types';
 
@@ -68,6 +68,19 @@ interface SeedDemoDataDependencies {
  * put is keyed by a deterministic stable id so re-runs after
  * dedup-TTL expiry upsert the same records.
  *
+ * Self-healing-on-every-deploy contract: every individual upsert
+ * across all three phases is wrapped via {@link tryRun}. A single
+ * item's failure (transient AWS error, write-time constraint
+ * violation, etc.) is collected into a per-call accumulator and
+ * does not skip the remaining items in its phase. After all phases
+ * run, collected failures are aggregate-thrown as a single error so
+ * EventBridge still routes the workflow into its failure-detection
+ * path (DLQ + CloudWatch alarm) and the outer `runSeedDemoData`
+ * records `markFailed` on the dedup row. Because every put is keyed
+ * by a deterministic stable id, the next deploy re-attempts every
+ * item — failed items eventually heal, successful items overwrite
+ * themselves with the same body.
+ *
  * Exported so the seeder test file can exercise it directly against
  * a mocked DynamoControlService; the production handler reaches it
  * through {@link SeedDemoDataDependencies.seedDemoGraph}.
@@ -84,13 +97,40 @@ declare const seedDemoGraph: (params: {
  */
 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).
+ * SSM parameter-path prefix that hosts every seeded dev user's
+ * password. The full path for a single user is
+ * `${SEED_USER_PASSWORD_PARAMETER_PREFIX}<email_safe>/password`
+ * where `<email_safe>` is `<user>_at_<domain>` (see
+ * {@link emailToSsmPath}). The trailing `/password` segment leaves
+ * room for additional per-user parameters under the same email
+ * prefix in future phases without renaming the existing entries.
  */
-declare const devPasswordForEmail: (email: string) => string;
+declare const SEED_USER_PASSWORD_PARAMETER_PREFIX = "/openhi/seed/users/";
+/**
+ * Map an email address to its canonical SSM parameter path. The
+ * `@` separator is replaced with the literal sentinel `_at_` so
+ * the resulting path is a single SSM-legal name. Throws when the
+ * email is empty, missing exactly one `@`, or contains characters
+ * that would produce an invalid SSM path.
+ *
+ * Example: `alice@codedrifters.com` →
+ * `/openhi/seed/users/alice_at_codedrifters.com/password`.
+ */
+declare const emailToSsmPath: (email: string) => string;
+/**
+ * Test seam: reset the module-scoped SSM client cache. Unit tests
+ * that swap in different mocks across `it` blocks call this in
+ * `beforeEach` so each test gets a fresh client instance.
+ */
+declare const __resetSsmClientForTests: () => void;
+/**
+ * Read a seeded dev user's password from SSM Parameter Store. The
+ * parameter is expected to be a `SecureString` provisioned out of
+ * band by an operator (see the runbook in phase 3 of #1249). On
+ * `ParameterNotFound`, the error message includes the exact
+ * expected path so the operator can copy-paste-fix.
+ */
+declare const fetchSeedUserPassword: (email: string) => Promise<string>;
 /**
  * Production Cognito provisioner backed by the AWS SDK. Reads the
  * user-pool id from the env var the lambda construct injects.
@@ -98,13 +138,21 @@ declare const devPasswordForEmail: (email: string) => string;
  * Idempotency contract:
  *   - On first invocation, calls `AdminCreateUser` (with
  *     `MessageAction: SUPPRESS` so no invitation email fires) then
- *     `AdminSetUserPassword` (permanent). Returns the new user's sub.
+ *     `AdminSetUserPassword` (permanent, from the SSM-sourced
+ *     value). 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.
+ *     `AdminGetUser` to read the existing user's sub, and **also
+ *     re-applies the current SSM-sourced password** via
+ *     `AdminSetUserPassword`. This is the rotation seam: operators
+ *     update the SSM SecureString value and re-publish the seed
+ *     event to push a fresh password down to Cognito.
+ *
+ * The SSM password is fetched once per email up-front so the new-
+ * user and rotation branches share the same value and at most one
+ * `GetParameter` call lands per `ensureUser` invocation.
  */
 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 };
+export { type CognitoProvisioner, SEED_DEMO_DATA_USER_POOL_ID_ENV_VAR, SEED_USER_PASSWORD_PARAMETER_PREFIX, type SeedDemoDataDependencies, __resetSsmClientForTests, emailToSsmPath, fetchSeedUserPassword, handler, productionCognitoProvisioner, runSeedDemoData, seedDemoGraph };

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

@@ -1,6 +1,6 @@
 import { WorkflowDedupClient } from '@openhi/workflows';
 import { EventBridgeEvent } from 'aws-lambda';
-import { d as DemoDevUser } from './events-CMG8xanm.js';
+import { d as DemoDevUser } from './events-DTgo2dcW.js';
 import { O as OpenHiContext } from './openhi-context-CaBH8SFo.js';
 import '@openhi/types';
 
@@ -68,6 +68,19 @@ interface SeedDemoDataDependencies {
  * put is keyed by a deterministic stable id so re-runs after
  * dedup-TTL expiry upsert the same records.
  *
+ * Self-healing-on-every-deploy contract: every individual upsert
+ * across all three phases is wrapped via {@link tryRun}. A single
+ * item's failure (transient AWS error, write-time constraint
+ * violation, etc.) is collected into a per-call accumulator and
+ * does not skip the remaining items in its phase. After all phases
+ * run, collected failures are aggregate-thrown as a single error so
+ * EventBridge still routes the workflow into its failure-detection
+ * path (DLQ + CloudWatch alarm) and the outer `runSeedDemoData`
+ * records `markFailed` on the dedup row. Because every put is keyed
+ * by a deterministic stable id, the next deploy re-attempts every
+ * item — failed items eventually heal, successful items overwrite
+ * themselves with the same body.
+ *
  * Exported so the seeder test file can exercise it directly against
  * a mocked DynamoControlService; the production handler reaches it
  * through {@link SeedDemoDataDependencies.seedDemoGraph}.
@@ -84,13 +97,40 @@ declare const seedDemoGraph: (params: {
  */
 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).
+ * SSM parameter-path prefix that hosts every seeded dev user's
+ * password. The full path for a single user is
+ * `${SEED_USER_PASSWORD_PARAMETER_PREFIX}<email_safe>/password`
+ * where `<email_safe>` is `<user>_at_<domain>` (see
+ * {@link emailToSsmPath}). The trailing `/password` segment leaves
+ * room for additional per-user parameters under the same email
+ * prefix in future phases without renaming the existing entries.
  */
-declare const devPasswordForEmail: (email: string) => string;
+declare const SEED_USER_PASSWORD_PARAMETER_PREFIX = "/openhi/seed/users/";
+/**
+ * Map an email address to its canonical SSM parameter path. The
+ * `@` separator is replaced with the literal sentinel `_at_` so
+ * the resulting path is a single SSM-legal name. Throws when the
+ * email is empty, missing exactly one `@`, or contains characters
+ * that would produce an invalid SSM path.
+ *
+ * Example: `alice@codedrifters.com` →
+ * `/openhi/seed/users/alice_at_codedrifters.com/password`.
+ */
+declare const emailToSsmPath: (email: string) => string;
+/**
+ * Test seam: reset the module-scoped SSM client cache. Unit tests
+ * that swap in different mocks across `it` blocks call this in
+ * `beforeEach` so each test gets a fresh client instance.
+ */
+declare const __resetSsmClientForTests: () => void;
+/**
+ * Read a seeded dev user's password from SSM Parameter Store. The
+ * parameter is expected to be a `SecureString` provisioned out of
+ * band by an operator (see the runbook in phase 3 of #1249). On
+ * `ParameterNotFound`, the error message includes the exact
+ * expected path so the operator can copy-paste-fix.
+ */
+declare const fetchSeedUserPassword: (email: string) => Promise<string>;
 /**
  * Production Cognito provisioner backed by the AWS SDK. Reads the
  * user-pool id from the env var the lambda construct injects.
@@ -98,13 +138,21 @@ declare const devPasswordForEmail: (email: string) => string;
  * Idempotency contract:
  *   - On first invocation, calls `AdminCreateUser` (with
  *     `MessageAction: SUPPRESS` so no invitation email fires) then
- *     `AdminSetUserPassword` (permanent). Returns the new user's sub.
+ *     `AdminSetUserPassword` (permanent, from the SSM-sourced
+ *     value). 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.
+ *     `AdminGetUser` to read the existing user's sub, and **also
+ *     re-applies the current SSM-sourced password** via
+ *     `AdminSetUserPassword`. This is the rotation seam: operators
+ *     update the SSM SecureString value and re-publish the seed
+ *     event to push a fresh password down to Cognito.
+ *
+ * The SSM password is fetched once per email up-front so the new-
+ * user and rotation branches share the same value and at most one
+ * `GetParameter` call lands per `ensureUser` invocation.
  */
 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 };
+export { type CognitoProvisioner, SEED_DEMO_DATA_USER_POOL_ID_ENV_VAR, SEED_USER_PASSWORD_PARAMETER_PREFIX, type SeedDemoDataDependencies, __resetSsmClientForTests, emailToSsmPath, fetchSeedUserPassword, handler, productionCognitoProvisioner, runSeedDemoData, seedDemoGraph };