Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(testing): document deferred development recovery verification
Josuéda5ca040dce3
diff --git a/docs/testing/password-recovery-dev-integration.md b/docs/testing/password-recovery-dev-integration.mdnew file mode 100644index 000000000..fff8f5480--- /dev/null+++ b/docs/testing/password-recovery-dev-integration.md@@ -0,0 +1,287 @@+# Manually verify password recovery with the development producer++Use this guide in a **separate, authorized manual session** after fetching PR #1056.+Audience: a developer or platform owner with access to the intended development+Member Registration producer, its test data and an approved recipient mailbox.+This guide describes the configured integration lane and a separate email/UI+journey. Neither lane was executed while implementing the structural redesign.+Both remain **NOT VERIFIED** until their own receipts are recorded.++## A. Obtain and build the published revision++From the intended main Evenfire checkout, inspect before changing anything:++```sh+pwd+git remote get-url origin+git branch --show-current+git status --short+git rev-parse HEAD+git fetch origin fix/issue-1055-password-admission-dos+```++Confirm the remote is `evenfire-ai/evenfire`. Preserve unrelated local work;+if switching would overwrite it, stop and use another clean checkout or agree on+its disposition. Do not hard reset, force checkout, or automatically stash it.+In a clean checkout already on the PR branch, use:++```sh+git merge --ff-only origin/fix/issue-1055-password-admission-dos+git rev-parse HEAD+```++If the branch is not checked out and no conflicting local work exists, switch+to the existing local branch with `git switch fix/issue-1055-password-admission-dos`+(or create its tracking branch with `git switch --track origin/fix/issue-1055-password-admission-dos`).+Then fast-forward as above. Divergence needs a decision; this guide does not+authorize rebasing or rewriting history. Compare the actual SHA with GitHub's+current PR head and record it in the receipt.++Use Node 24 and the checked-in lockfiles:++```sh+node --version+npm --prefix packages/workflow-runtime-core ci+npm --prefix packages/workflow-runtime-core run build+npm --prefix control-api ci+npm --prefix external-rest-api ci+npm --prefix control-api run build+npm --prefix external-rest-api run build+node scripts/ci/password-recovery-suite-contract.mjs verify+```++The composed local private suite needs the built External REST app. Each service+owns its dependencies; another CI job's artifacts do not satisfy this prerequisite.+For the optional later UI journey, install/build Profile UI according to its+live local guidance. Do not treat a local UI attached to older backend images as+verification of this revision; record the backend revisions separately.++## B. Establish the real development producer++The known setup commands below are reference context for a later authorized+session, not proof that Member Registration is deployed in this cluster:++```sh+gcloud container clusters get-credentials clerum-dev \+ --zone=us-central1-a --project=eventfire-491421 \+ --account=<authorized-dev-account>+kubectl config set-credentials \+ gke_eventfire-491421_us-central1-a_clerum-dev \+ --exec-arg=--account=<authorized-dev-account>+LOCAL_KUBE_CONTEXT=gke_eventfire-491421_us-central1-a_clerum-dev npm run ui+```++Earlier read-only discovery found no `registration` namespace in that context.+The Control API configuration referenced the external registration hub at+`registration.evenfire.ai`; its deployment ownership, version, database and+isolation were not established. Reconfirm these facts. Do not select the first+similarly named service or infer the producer from the UI launch command.++After access is authorized, use explicit-context read-only discovery:++```sh+DEV_CONTEXT=gke_eventfire-491421_us-central1-a_clerum-dev+kubectl --context="$DEV_CONTEXT" get namespaces+kubectl --context="$DEV_CONTEXT" get services --all-namespaces+kubectl --context="$DEV_CONTEXT" get deployments --all-namespaces \+ -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,IMAGES:.spec.template.spec.containers[*].image+```++Confirm the actual namespace/service/deployment with its owner. Read only the+specific non-secret endpoint field from the confirmed configuration object;+do not dump Secrets, environment files or whole configuration objects.+For a confirmed Deployment, inspect its image and the running Pod image ID+with context-qualified commands and compare the immutable image provenance+with the producer's source revision. Record the actual deployed revision.+Ask the owner to identify the producer database, tenant/key binding, recipient+policy and whether the target is isolated or approved for this synthetic write.+An image tag, HTTP health response or UI screenshot alone does not establish+version, database identity or permission to send email.++If the producer is outside this cluster, discover it through its actual hosting+owner. The GKE UI workflow does not create a supported port-forward to it.+If a confirmed in-cluster producer needs a forward, obtain its exact Service+port and namespace first. Use a task-owned loopback forward in a dedicated+terminal, without inventing names or ports:++```sh+kubectl --context="$DEV_CONTEXT" -n "$VERIFIED_NAMESPACE" port-forward \+ --address=127.0.0.1 "service/$VERIFIED_SERVICE" ":$VERIFIED_SERVICE_PORT"+```++Use the allocated local port shown by that process only for this session, and+stop the forward afterward. Confirm any network/proxy requirements with the+owner; do not port-forward or mutate a shared environment without authorization.++## C. Provide configuration securely++Use an approved credential store or secure interactive entry into process+memory. In a local Bash shell, disable tracing and prompt without echo:++```bash+set +x+read -r -s -p 'Isolated Control API PostgreSQL admin DSN: ' CONTROL_API_REAL_PG_ADMIN_URL; printf '\n'+read -r -s -p 'Authorized producer PostgreSQL DSN: ' CONTROL_API_REAL_MEMBER_REGISTRATION_PG_URL; printf '\n'+read -r -s -p 'Verified producer API base URL: ' CONTROL_API_MEMBER_REGISTRATION_SERVICE_BASE_URL; printf '\n'+read -r -s -p 'Authorized producer HMAC secret: ' CONTROL_API_MEMBER_REGISTRATION_HMAC_SECRET; printf '\n'+export CONTROL_API_REAL_PG_ADMIN_URL CONTROL_API_REAL_MEMBER_REGISTRATION_PG_URL+export CONTROL_API_MEMBER_REGISTRATION_SERVICE_BASE_URL CONTROL_API_MEMBER_REGISTRATION_HMAC_SECRET+```++The first DSN must target an authorized disposable PostgreSQL 16 instance with+CREATE/DROP DATABASE permission. The second must identify the producer's+explicitly authorized test database. They have different effects. Do not point+the admin DSN at production or an unrelated shared database.++The runner requires these four variables. Successful authentication also+requires the matching producer tenant and HMAC key ID; confirm whether+`CONTROL_API_MEMBER_REGISTRATION_TENANT_ID` and+`CONTROL_API_MEMBER_REGISTRATION_HMAC_KID` need explicit values. Verify that+`CONTROL_API_MEMBER_REGISTRATION_MODE=remote` matches the intended producer+configuration. Do not accept test defaults as evidence of the deployed binding.+Confirm the configured redirect/app metadata against the producer's allowed+URLs; the standalone configured suite is not a deployment compatibility test.++Never echo these variables, persist them in a receipt, paste literal values into+shell commands, or enable `set -x`. Do not print `.env` contents or URLs containing+credentials. Test runners may report operational errors: inspect locally,+sanitize before sharing and do not publish raw producer/database logs.+Unset all supplied secrets after the session, including optional credential+inputs, and stop any task-owned port-forward or test process.++## D. Authorize the actual data and email effects++Before running, record owner approval for these concrete effects:++- A random `bug192_flow_*` Control API database is created, migrated and filled+ with synthetic users, invitations and admission state; teardown drops it.+ DELETE statements in setup operate inside that temporary database.+- The producer receives real authenticated registration/validation requests and+ stores a synthetic `invitation_flow_registrations` row for a random+ `issue1055-*` address under `example.invalid`.+- Producer `ensureApp`/`ensureLatestAppConfig` may create `apps`/`app_configs`+ rows. Existing teardown deletes flow rows by the generated test email but+ does **not** remove these possible app/config records.+- Registration calls the real invitation email path. Checked-in producer+ deployment configuration uses Postmark SMTP. A non-delivering configuration+ has not been established; outbound email may be attempted, and an invalid+ recipient can cause rejection/bounce rather than delivery.++The configured suite's generated address is not a configurable permitted+mailbox. Confirm that this exact synthetic recipient/write scope is approved+and compatible with the development email service before execution. Use a+separate permitted mailbox for the delivery/UI journey below. Do not silently+change the runner to skip email, change recipients or omit cleanup.++Clearly identifiable synthetic development app/config records may remain when+accepted by the owner. Record them by sanitized identifier and agree on their+later cleanup. This acceptance does not disable the runner's existing flow-row+DELETE or temporary-database DROP. If teardown fails, confirm the exact generated+resources before any manual deletion; never broadly delete producer data.++## E. Run the configured integration lane++The final checked-in command and physical suite remain:++```sh+bash scripts/ci/run-pr1056-private-recovery-postgres.sh configured+```++It selects exactly+`control-api/test/bug192.passwordRecovery.memberRegistration.realPostgres.integration.test.ts`+through the strict suite manifest. Expect one physical suite and one passing+scenario, containing admission-denial, real stored signed proof, preview/row+binding, wrong-email/row negatives, reset session and later-login assertions.+Require process exit zero, nonzero passing collection and **zero skipped tests**.+The runner rejects missing files/environment and skipped/zero-test results.+The configured suite does not start or replace the producer, and does not prove+public External REST cookies or actual mailbox delivery.++If collection skips, configuration is missing, authentication fails or the+producer/database cannot be identified, record **NOT VERIFIED**. For a test+failure, record its phase and sanitized error category: configuration/tenant,+producer registration, persisted proof, validation, Control API mutation/session,+or teardown. Do not substitute mocked receipts. Record the exact source SHA,+producer revision, permitted data effects and cleanup result.++`local` is a separate real-producer lane requiring the Member Registration source+checkout, installed `tsx`, two disposable databases and the built HTTP child;+see [private runner reference](pr1056-private-recovery-postgres.md). It is not+configured-producer or email-delivery evidence. Do not run `all` merely to obtain+a green status without both lanes' explicit authorization.++## F. Verify actual email delivery and the public UI journey++Use the confirmed development invitation email service and a dedicated synthetic+account with an owner-approved mailbox. Do not add a test mail system for this+journey. Establish the intended Profile UI and External REST origins and backend+revisions, and ensure no unrelated account uses the synthetic address.++1. Request recovery through the intended Profile UI, which calls public+ `POST /api/v1/auth/password-reset-request`. Check its non-enumerating success+ without assuming that response proves delivery. Observe the actual message+ arriving in the permitted mailbox; record a redacted timestamp/message receipt.+2. Inspect the destination origin/path privately before opening the link. The+ producer proof must bind to the intended invitation token/email/row; the row+ ID and invitation token are distinct. Do not publish the URL or proof.+3. Use a valid fresh link and confirm the reset view shows the intended account.+ Separately exercise invalid proof and mismatched email/row input using only+ synthetic records: they must not update credentials, create a cookie or expose+ another account. Avoid modifying or probing an unrelated invitation.+4. Submit an approved valid replacement password once. Confirm the correct+ account identity and authenticated session. Inspect cookie **attributes**+ privately: `profile_session`, HttpOnly, expected Path/SameSite and Secure for+ the intended HTTPS environment. Do not record cookie or token values.+5. Confirm session hydration and navigation to the authenticated view, including+ a refresh. The UI must not automatically replay the reset after a hydration+ failure. Record the displayed account identity in sanitized form.+6. Reuse the consumed proof once deliberately: completion must be rejected,+ credentials must stay unchanged and no new authenticated session may be+ published from that replay. Confirm sibling reset invalidation using only+ owner-approved synthetic links where applicable.+7. Where normal admission permits, log in with the new password and verify the+ same account. Inspect only the authorized synthetic account/invitation state+ to confirm unrelated records were unaffected.++Do not deliberately saturate shared dev login capacity, consume another user's+budget or inject wire/database/email failures into shared services. Busy-owner,+unknown COMMIT, FATAL/lost acknowledgement, storage outage and connection cleanup+faults belong in a separately authorized isolated environment. A normal admission+429 must remain bounded and must not trigger automatic reset replay.++Configured SQL/producer integration and this delivery/UI journey are separate+evidence lanes. Passing either does not certify the other, and source/local+synthetic-browser results do not certify deployed versions.++## G. Record and share a sanitized receipt++Copy this checklist into the authorized review record:++```text+Date / tester:+PR SHA fetched and tested:+Control API / External REST / Profile revisions actually running:+Member Registration immutable image / source revision:+Verified dev context and confirmed producer owner/service:+Authorized test database identity (no DSN):+Authorization for synthetic SQL, producer effects and email:+Configured command / exit code:+Physical suites / passed / failed / skipped counts:+Manual email receipt and timestamp (redacted):+Link origin and trusted account/token binding (no URL/proof):+Reset / invalid / mismatch / consumed-proof results:+Cookie attributes / session identity / hydration / navigation:+New-password login under ordinary admission:+Unrelated synthetic account/invitation state:+Flow-row cleanup / temporary database drop:+Remaining synthetic app/config records and owner disposition:+Stopped task-owned processes / forwards / unset credentials:+Unverified or failed paths:+Reviewer / owner merge-sign-off decision:+```++A later authorized PR update should state the exact tested SHA and producer+revision, separate the two evidence lanes, include counts and sanitized outcomes,+and retain any unresolved limitation. Never attach credentials, full logs,+mailbox content, link tokens, database URLs or session cookies. Missing or skipped+integration remains **NOT VERIFIED**; it is not a merge certification.diff --git a/docs/testing/pr1056-private-recovery-postgres.md b/docs/testing/pr1056-private-recovery-postgres.mdindex ddbd215b5..0b5d15f07 100644--- a/docs/testing/pr1056-private-recovery-postgres.md+++ b/docs/testing/pr1056-private-recovery-postgres.md@@ -5,6 +5,22 @@ real Member Registration producer and isolated PostgreSQL databases. The publicPostgreSQL job checks that both pinned suite files exist before excluding them;that check proves suite discoverability, not producer execution.+For later configured dev discovery, secure configuration, actual data/email effects and a+separate mailbox/UI journey, use the [manual development guide](password-recovery-dev-integration.md).+Neither private mode nor real email delivery was run during the structural redesign.++Build the relevant locked service dependencies first:++```sh+npm --prefix packages/workflow-runtime-core ci+npm --prefix packages/workflow-runtime-core run build+npm --prefix control-api ci+npm --prefix external-rest-api ci+npm --prefix control-api run build+npm --prefix external-rest-api run build+node scripts/ci/password-recovery-suite-contract.mjs verify+```+Run the producer-backed lane from the Evenfire repository root:```sh@@ -16,7 +32,8 @@ scripts/ci/run-pr1056-private-recovery-postgres.sh all`local` runs `control-api/test/r4l1.resetPasswordPayload.externalRest.realPostgres.integration.test.ts`.It requires an isolated PostgreSQL 16 admin DSN in `CONTROL_API_REAL_PG_ADMIN_URL`,the Member Registration source checkout in `EVENFIRE_MEMBER_REGISTRATION_ROOT`,-and that checkout's installed `tsx` dependencies. The suite creates temporary+that checkout's installed `tsx` dependencies, and `external-rest-api/dist/app.js`.+The local public consumer runs as a bounded built HTTP child. The suite creates temporarycontrol and producer databases and launches the real local Member Registrationservice. Use a disposable local PostgreSQL instance only.@@ -27,7 +44,11 @@ It requires `CONTROL_API_REAL_PG_ADMIN_URL`,`CONTROL_API_MEMBER_REGISTRATION_HMAC_SECRET`. The service URL and HMAC must referto a real authorized Member Registration producer and its real PostgreSQL data.The test creates a temporary Control API database and observes the configured-producer database; it does not start or replace that producer.+producer database; it does not start or replace that producer. Teardown deletes the+generated email's flow rows and drops the temporary Control API database, but does+not remove possible producer `apps`/`app_configs` rows. Registration may invoke+Postmark SMTP; authorize the generated synthetic recipient and actual email scope+before running. This suite does not verify mailbox delivery.`all` runs both modes sequentially and requires both sets of prerequisites. Therunner verifies each exact suite file, requires at least one passing test, and