236 lines
15 KiB
Markdown
236 lines
15 KiB
Markdown
# Sign-up Facts intake
|
|
|
|
Task [#46](https://git.sendico.io/tech/sxchnge/issues/46), branch
|
|
`identity-facts-46`. Primary module: identity-facts; secondary modules: auth,
|
|
customer creation, runtime, shared database source and Flutter error feedback.
|
|
Delivery: [PR #47](https://git.sendico.io/tech/sxchnge/pulls/47), targeting `main`.
|
|
|
|
## Registration response correction
|
|
|
|
Follow-up [#57](https://git.sendico.io/tech/sxchnge/issues/57), branch
|
|
`identity-facts-57`, corrects the registration success status to HTTP 201 Created.
|
|
Sendico's individual creation handler returns 201; the original adapter and test
|
|
fixture incorrectly required 200. A successful registration therefore left a
|
|
pending customer with an unresolved claim and `signup_attention_required`.
|
|
The adapter now checks the exact status per operation before validating receipts:
|
|
201 for registration and 200 for Facts intake. Other statuses, including other
|
|
2xx responses, remain failures. Malformed receipts and uncertain registrations
|
|
still require the existing recovery rules.
|
|
|
|
On 2026-10-17, the affected local signup was reconciled using its registration
|
|
correlation in Sendico logs and an authenticated organization-scoped individual
|
|
GET. A conditional majority write bound that confirmed individual to the existing
|
|
local claim, preserving the saved facts, namespace and registration request.
|
|
The rebuilt BFF resumed the public activation-resend flow: Facts intake returned
|
|
a persisted receipt and the endpoint returned 202 after activation-email queue
|
|
acceptance. No replacement individual was registered. The account remains
|
|
pending until the customer confirms the email; queue acceptance does not prove
|
|
inbox delivery.
|
|
|
|
Recovery also exposed a notification worker lifetime issue: its NATS subscription
|
|
retained the 20-second startup context and was automatically unsubscribed after
|
|
that deadline. Resource provisioning now has its own bounded context, while the
|
|
subscription follows the service lifetime and closes at shutdown. A regression
|
|
test checks that releasing provisioning leaves the subscription context active,
|
|
and service cancellation still ends it.
|
|
|
|
The rebuilt worker processed the queued activation message. The live Resend
|
|
provider rejected it with `provider_authentication_failed` (HTTP 401 or 403),
|
|
leaving delivery in `failed` after one attempt. The configured API key/sender
|
|
authorization must be corrected before sending another activation email. Rotate
|
|
the credential securely with `make email`, wait for Vault Agent to refresh it,
|
|
restart notifications so it reloads its environment, then use activation resend
|
|
with a new idempotency key. Do not replay the failed notification as a success or
|
|
mark the customer active on their behalf.
|
|
|
|
Validation passed: `GOFLAGS=-p=2 make test` (all backend race tests and canonical
|
|
frontend suites), `make lint-backend`, focused provider/identity race tests and
|
|
notification bus/app race tests. The HTTP 201 regression first failed against the
|
|
old adapter and passed after correction. An earlier full run hit a database
|
|
credential-rotation timing failure at `rotation_test.go:249` during the Docker
|
|
build; the isolated race-test retry and both subsequent full runs passed.
|
|
Local BFF and notifications images were rebuilt with fresh upstream manifests
|
|
and resolved stable digest pins; the BFF, session sidecar and notifications
|
|
services are healthy. NATS shows the worker still waiting for deliveries beyond
|
|
the startup deadline, with no pending or unacknowledged jobs. Live email delivery
|
|
is blocked by provider authorization as described above. No security scans were
|
|
requested or run. Unrelated notifications runtime settings are excluded from
|
|
the task commits.
|
|
|
|
## Behavior and boundaries
|
|
|
|
With `api.sendico` configured, the product BFF creates the local pending customer
|
|
and activation token atomically, then registers an independent individual through
|
|
Sendico's public HTTP API and submits the sign-up assertions. It persists the
|
|
intake receipt before sending activation email or returning sign-up success.
|
|
Activation resend runs the same handoff; activation checks the receipt in its
|
|
local transaction, without external I/O. A failed receipt check rolls back token
|
|
consumption and leaves the account pending. Existing active customers are not
|
|
backfilled or blocked at login.
|
|
|
|
The adapter consumes these existing Sendico contracts:
|
|
|
|
- `POST /individuals/{organization_ref}`, empty body, HTTP 201 registration
|
|
receipt containing `subject_ref` and `registered_at`.
|
|
- `POST /identity_facts/{organization_ref}`, HTTP 200 immutable intake receipt
|
|
containing `submission_ref`, `subject_ref` and `accepted_at`.
|
|
|
|
The configured API prefix precedes both paths. See Sendico
|
|
[individual subjects](https://git.sendico.io/tech/sendico/src/branch/main/docs/api/individual-subjects.md)
|
|
and [Facts intake](https://git.sendico.io/tech/sendico/src/branch/main/docs/api/identity-facts-intake.md).
|
|
The only assertions sent are `full_name`, normalized `email` and
|
|
`external_customer_ref` (the local customer ID). Passwords, password hashes,
|
|
activation tokens, session credentials and device data never enter the adapter.
|
|
The input name is retained as a full name, without guessing name parts. No facts
|
|
are marked verified; acceptance does not establish identity, KYC completeness,
|
|
verification, limits or payout eligibility. The existing KYC preview is unchanged.
|
|
|
|
Only the BFF owns Sendico credentials and organization scope. Local customer
|
|
models have no organization, membership or platform permissions. HTTP DTOs and
|
|
mappers stay in `providers/sendico`; the handoff operates on domain facts and
|
|
receipts in `identity`. Flutter continues through its DTO, mapper, service,
|
|
model and provider layers. It never calls Sendico or supplies subject references.
|
|
|
|
## Configuration and rollout
|
|
|
|
Add this block under `api` in the product service configuration, retaining
|
|
`api.notifications`:
|
|
|
|
```yaml
|
|
sendico:
|
|
api_url: https://your-sendico-host/api/v1
|
|
organization_ref: <provisioned-SXCHNGE-organization-object-id>
|
|
source_account_ref: <provisioned-integration-account-object-id>
|
|
token_file: /run/sxchnge/sendico-token
|
|
```
|
|
|
|
Resolve the real IDs from the target Sendico deployment. The integration account
|
|
must be a member of the SXCHNGE organization with the existing organizations
|
|
`update` permission; reconciliation GET requests also require `read`. The token
|
|
must be a full, unexpired Sendico access JWT whose `id` claim is that account.
|
|
The adapter inspects claims only to protect the replay namespace; Sendico checks
|
|
the signature and authorizes every call. No login, refresh or privileged account
|
|
provisioning is performed by this adapter.
|
|
|
|
Keep the token in Vault at `services/bff/sendico`, field `access_token`. Render it
|
|
with the deployment's Vault Agent into the configured private runtime file; give
|
|
only the BFF policy read access to that KV path. Endpoint, organization and source
|
|
IDs remain in service YAML. For the local stack, configure
|
|
`infra/local/bff/runtime.yml`, render to the BFF's existing `/run/sxchnge` tmpfs,
|
|
and extend its Vault Agent policy/template for this provisioned secret. These
|
|
deployment values and secret provisioning are deliberately not guessed or
|
|
enabled by the example. Do not place tokens in Git, browser builds or shell
|
|
history. Refresh the file atomically before expiry using the same Sendico account;
|
|
the adapter rereads it on every request. Startup rejects missing, expired or
|
|
mismatched credentials and rejects Sendico configuration without notifications.
|
|
|
|
HTTPS is required except for loopback HTTP test/development endpoints. Redirects
|
|
are rejected and each HTTP call has a four-second timeout. Unexpected response
|
|
statuses (registration requires 201; Facts intake requires 200), malformed/truncated
|
|
receipts, invalid identifiers, wrong subjects and unsuccessful envelopes never
|
|
count as acceptance. Upstream error bodies are not surfaced.
|
|
|
|
Omitting `api.sendico` keeps existing local-only behavior. Enabling it also gates
|
|
activation for previously pending customers; use activation resend to submit
|
|
their saved name/email before confirming their old link. There is no automatic
|
|
bulk migration. Changing endpoint, organization or source account changes the
|
|
adapter fingerprint and blocks existing bindings for explicit reconciliation.
|
|
Token rotation for the same account retains that fingerprint. Plan such changes
|
|
as migrations; never reset a binding just to bypass the check.
|
|
|
|
## Persistence, retries and recovery
|
|
|
|
The local `signup_facts` collection uses the customer ID as `_id`, so its unique
|
|
primary key coordinates concurrent requests and separate BFF instances. It stores
|
|
an immutable sign-up facts snapshot, adapter fingerprint, random registration
|
|
request correlation, registration claim, subject and confirmed receipt. It uses
|
|
the shared database repository and connection lifecycle with majority writes and
|
|
primary majority reads, overriding weaker connection defaults. No external call
|
|
runs in a database transaction. Snapshots and bindings contain personal data and
|
|
must follow the customer data retention policy; no TTL silently removes replay
|
|
state, and customer deletion does not delete the immutable Sendico submission.
|
|
|
|
Once a subject is stored, intake retries use
|
|
`sxchnge:signup:<local-customer-id>` as `source_submission_ref`. Sendico's
|
|
organization/authenticated-account/source-reference uniqueness returns the
|
|
original receipt for that subject. Retries send the saved snapshot even if a
|
|
later request changes name or email. Losing the HTTP receipt or a local receipt
|
|
write is recoverable by replay. A saved receipt skips subsequent external calls.
|
|
Retrying sign-up still requires the original password; active, archived or
|
|
otherwise conflicting accounts cannot be resumed as a new customer.
|
|
|
|
**Individual registration is not idempotent.** The BFF commits a claim before
|
|
dispatch and never expires or automatically retries that registration. It cannot
|
|
prove that a timed-out request, malformed response or failed local binding write
|
|
did not create a subject. Another request sees an in-progress claim as temporarily
|
|
unavailable for 30 seconds; an older unresolved claim requires support. The
|
|
registration caller immediately reports assistance on an uncertain failure. An
|
|
accepted registration is saved with a short independent context even if the
|
|
browser disconnects. A crash before dispatch can also require reconciliation.
|
|
This trades automatic recovery for avoiding duplicate subjects under the current
|
|
upstream contract; there is no distributed exactly-once guarantee.
|
|
|
|
For an unresolved registration, operators must stop requests for the affected
|
|
customer and inspect the saved `registrationRequest` plus Sendico identity logs
|
|
(`X-Request-ID`, operation `subject_register`) under the configured account and
|
|
organization. A successful registration's server-issued `record_ref` identifies
|
|
the candidate subject. Confirm it using the organization-scoped individual GET
|
|
API before atomically setting the matching local binding's `subjectRef` and
|
|
clearing `registering`; retain its snapshot, fingerprint and request reference.
|
|
If a local binding write failed after receipt, BFF diagnostics also contain the
|
|
subject reference. If authoritative records prove no subject was created, an
|
|
operator may clear the claim after fixing the dependency. If neither result can
|
|
be established, leave it blocked; never register a speculative replacement.
|
|
Resume sign-up with the original credentials or activation resend after this
|
|
repair. These are controlled operational repairs, not customer API endpoints.
|
|
|
|
HTTP 503 `signup_attention_required` maps to typed shared auth and verification
|
|
state and localized EN/RU support guidance, including activation resend recovery.
|
|
Other intake/receipt failures remain temporary service
|
|
failures. Form input is retained, duplicate submissions stay disabled during
|
|
loading, and neither failure navigates to an email-sent screen or creates a
|
|
session. The existing support channel must be available to handle reconciliation.
|
|
|
|
## Measurement and UX review
|
|
|
|
The existing [auth journey](ux/auth-journeys.md) keeps its attempt, retry,
|
|
abandonment and 30-minute settled inactivity rules. `auth_signup_succeeded` now
|
|
requires server confirmation of configured intake plus activation queue acceptance;
|
|
it remains an intermediate step and email confirmation remains the terminal
|
|
onboarding outcome. Sign-up dependency failures and assistance outcomes use the
|
|
existing allowlisted `unavailable` analytics category; verification assistance
|
|
uses it too. Retries retain the journey
|
|
and operation semantics. No names, emails or provider response bodies are added.
|
|
|
|
`sxchnge_signup_facts_total{outcome}` records `accepted`, `replayed`,
|
|
`unavailable` and `attention_required` handoff attempts;
|
|
`sxchnge_signup_facts_duration_seconds` measures their latency. Counts are
|
|
attempts, not distinct users. Use unavailable/attention counts divided by total
|
|
handoff attempts for operational failure rates; use the existing correlated auth
|
|
journey for conversion, duration and abandonment. Structured handoff logs include
|
|
local customer and random registration request references for support correlation,
|
|
without asserted values, credentials or raw errors. IDs are never metric labels.
|
|
The product team uses the distinction to separate retryable intake outages from
|
|
registration reconciliation. The default client analytics sink remains in memory;
|
|
production retention and cross-device conversion correlation remain deployment
|
|
gaps, as documented by the existing journey contract.
|
|
|
|
Review covers loading suppression, input preservation, success only on confirmed
|
|
handoff, temporary retry and assistance states, existing navigation, mobile layout,
|
|
text scaling and live-region error feedback. Focused tests cover these states,
|
|
the mapped backend error, non-inflated client success, immutable retry payloads,
|
|
credential rotation, timeout/cancellation/redirect behavior, receipt validation,
|
|
privacy-safe errors, concurrent durable claims and activation rollback. The tests
|
|
use disposable local MongoDB and a simulated Sendico HTTP server; they do not
|
|
create live subjects or send email. Live integration and support operations must
|
|
be verified against provisioned deployment credentials before enabling the block.
|
|
The EN/RU error state is exercised at a 390px viewport with 1.5x text scaling;
|
|
existing keyboard regression tests and a code review of the live-region semantics
|
|
cover the unchanged controls. No manual browser or screen-reader walkthrough
|
|
against a live Sendico deployment was performed.
|
|
|
|
The initial sign-up assertion remains a separate immutable submission. Optional
|
|
profile/ID/selfie collection, later account uploads and reviewed limits are now
|
|
covered by [Customer identity verification](identity-verification.md), task #48.
|
|
Proofs are not required to activate or log into a basic account.
|