### Singpass & Corppass

Package `soq-sg-singpass` - permissions 90130-90133 (90134-90139 reserved) - implementation guide: [Singpass Login Module](../engineering/modules/singpass/MODULE.md)

#### What this module does

Singpass lets learners log in, sign up, or link an existing SOQ account using Singapore national digital identity. SOQ stores the masked verified identity for display and the encrypted full NRIC/FIN for downstream Singapore reporting such as TPGateway. Corppass/business login is not built yet.

#### UI map: where to click

| UI area | Path | What operators do | Key buttons / controls |
|---|---|---|---|
| Public login | `/login` | Verify the Singpass button appears only when enabled. | **Log in with Singpass** |
| Student panel | `/panel/setting` -> Login history | Learner links/unlinks Singpass and sees masked verified identity. | **Link Singpass**, **Unlink** |
| Admin settings | `/admin/singpass` | Configure mode, Client ID, signup policy, redirect/JWKS values and key pairs. | **Save settings**, **Generate keys / Rotate keys**, **Prune retired keys** |
| Linked identities | `/admin/singpass/identities` | Search linked users by name/email/NRIC and unlink if required. | Search filter, **Unlink** |

#### Permissions

| Permission | Purpose |
|---|---|
| `admin_sg_singpass` | Parent menu / module access |
| `admin_sg_singpass_settings` | Settings and key management |
| `admin_sg_singpass_identities` | Linked identity list |
| `admin_sg_singpass_unlink` | Admin unlink action |

Run `php artisan soq:seed-singpass` to install sections and admin grants.

#### Field guide

| Field / control | What to enter | Impact |
|---|---|---|
| Show "Log in with Singpass" and allow linking | On only after keys and Client ID are ready. | Shows login button and panel link card. |
| Mode | `mock`, `staging`, or `production`. | Mock uses local sample personas and is refused on production. |
| Client ID | App ID from Singpass Developer Portal. | Required for staging/production login. No client secret is used. |
| Create a student account for new Singpass users | Usually on. | If off, only already-linked accounts can use Singpass. |
| Redirect URI | Value shown on settings screen. | Must be registered exactly in the portal. |
| JWKS URL | Value shown on settings screen. | Portal uses it to verify SOQ's signing keys. |
| Rotate keys | Generates a new key pair. | New logins use the latest key; old keys remain for validation. |
| Prune retired keys | Removes old keys after safe age. | Use after rotation is stable. |

Settings bag: `soq_sg_singpass_settings`. Private keys and full NRIC/FIN values are encrypted with `APP_KEY`.

#### First-time setup

1. Run `php artisan migrate`.
2. Run `php artisan soq:seed-singpass`.
3. Open `/admin/singpass`.
4. Click **Generate keys** if no key pair exists.
5. Register Redirect URI, JWKS URL and scopes in Singpass Developer Portal.
6. Enter the Staging Client ID.
7. Set `Mode = staging`, turn on Singpass and save.
8. Open `/login` in a private browser and test with a Singpass staging persona.
9. Open `/admin/singpass/identities` and confirm the linked user appears.

#### UAT script

| Step | Action | Expected result |
|---|---|---|
| 1 | Enable mock mode locally. | Login page shows Singpass test mode. |
| 2 | Sign up with a mock persona whose email is new. | SOQ creates a student account and links identity. |
| 3 | Try a persona whose email already exists. | User must log in with password and link from panel; no unsafe email merge. |
| 4 | Link Singpass from `/panel/setting`. | Login history card shows verified name and masked NRIC/FIN. |
| 5 | Unlink from panel. | Identity removed; user still needs another login method. |
| 6 | Admin searches `/admin/singpass/identities`. | Search by name/email/full NRIC finds the linked identity. |
| 7 | Admin clicks **Unlink**. | Identity unlinked and user can no longer use Singpass until linking again. |
| 8 | Rotate keys. | New active key appears; old keys remain until pruned. |

#### Daily operations

- Check linked identities only when investigating learner login or reporting identity mismatches.
- Do not unlink identities without confirming the learner has password, Google, Facebook, or another login method.
- Rotate keys as part of security maintenance, then prune retired keys only after at least one hour.
- Keep mock mode off in production.

#### Troubleshooting

| Symptom | Check |
|---|---|
| Singpass button missing | Module disabled, route cached, or production refusing mock mode. |
| Portal rejects callback | Redirect URI in portal must exactly match the settings screen value. |
| Login says no account | Signup switch may be off; user must link from an existing account. |
| Learner cannot link in panel | Role needs the Profile Settings panel permission. |
| Stored identity unreadable after deployment | `APP_KEY` changed; encrypted identities/keys must be regenerated or relinked. |
| Admin cannot unlink | Role needs `admin_sg_singpass_unlink`. |

#### Security notes

- Accounts are never merged by email alone.
- Full NRIC/FIN is encrypted and should not be exported casually.
- Corppass is not implemented; do not promise corporate login until it is built.