# Trusted MNO login design

## Status

The existing `trusted_login` implementation is intentionally unchanged by the current security-hardening work. It must remain disabled or restricted at the gateway until the MNO proof described below is available.

## Trust boundary

A phone number and a request field such as `source=mno` are identifiers, not authentication evidence. `propertyfin` may issue a customer session without a password or SMS OTP only after it has independently verified proof supplied by the trusted mobile network operator.

The verified MNO result must establish both:

1. the identity of the participating MNO or approved aggregator; and
2. current possession of the SIM/MSISDN being used to log in.

## Preferred flow

1. The customer application starts the MNO number-verification flow.
2. The MNO returns a short-lived, single-use authorization artifact.
3. The application sends that artifact to `propertyfin`; it does not send a phone number as authoritative proof.
4. `propertyfin` validates the artifact directly with the MNO, or validates a signed assertion using pinned issuer metadata and current public keys.
5. `propertyfin` obtains the verified MSISDN from the validated result, normalizes it to E.164, and finds or provisions the customer.
6. `propertyfin` atomically consumes the artifact identifier and issues a least-privilege Miliki customer token.

CAMARA/Open Gateway Number Verification is preferred when the MNO supports it. For a direct server-to-server integration, use mutual TLS together with a signed JWT or signed request body.

## Required verification

The integration must reject the request unless all applicable checks pass:

- the TLS client certificate belongs to the configured MNO, when mutual TLS is used;
- the assertion signature validates against a pinned or securely discovered MNO key;
- `iss` identifies the configured MNO;
- `aud` identifies the Miliki trusted-login endpoint;
- `exp` and `nbf` are valid with a small clock-skew allowance;
- `jti` or the equivalent transaction identifier has not previously been used;
- the authentication method represents network/SIM possession where the provider exposes an `amr` claim;
- the verified MSISDN is present and valid E.164;
- the MNO/aggregator and tenant are enabled in Miliki configuration.

Number-verification proof should expire within five minutes and be accepted only once. IP allowlisting is defense in depth, not a replacement for cryptographic client authentication.

## Proposed endpoint

Use a dedicated endpoint instead of the generic method switch:

```text
POST /api/v1/auth/mno/trusted-login
```

The endpoint should accept only the provider authorization artifact and correlation metadata. If a phone number is included by the client, it must only be compared with the MNO-verified value; it must never override that value.

## Token and account policy

- Provision a customer only after successful MNO verification.
- Issue only the normal customer scopes required by the channel.
- Give the access token an explicit short lifetime and do not return a refresh token unless the agreed flow requires one.
- Require step-up authentication for phone-number changes, ownership/KYC changes, payment destination changes, and other high-risk operations.
- Define an account-recovery policy for SIM swaps, recycled numbers, and number portability.

## Logging and monitoring

Log the provider, correlation ID, result, failure reason, normalized issuer, and a one-way or masked representation of the MSISDN. Never log the raw assertion, access token, private key, shared secret, or complete phone number.

Alert on repeated assertion replay, invalid signatures, issuer/audience mismatch, unusual account creation volume, and rapid use of one MSISDN across multiple devices.

## Acceptance tests

- a valid, unused MNO proof creates or signs in the expected customer;
- a direct public request containing only `source` and a phone number fails;
- invalid signature, issuer, audience, or authentication method fails;
- expired and not-yet-valid assertions fail;
- a replayed `jti` fails, including concurrent replay attempts;
- a submitted phone number that differs from the MNO-verified number fails;
- disabled providers and revoked keys fail;
- logs and audit records contain no raw proof or issued access token.

## Information needed from the MNO

Before implementation, obtain the protocol/API specification, issuer and audience values, JWKS or certificate lifecycle, proof lifetime, replay identifier, MSISDN claim format, error model, sandbox credentials, production network restrictions, key-rotation process, and incident/revocation contacts.