시스템을 See-KidLearn에 연동하기

# TASK: Implement "Sign in with See-KidLearn" (OAuth 2.0 + OIDC) in this project

You are integrating this application with **See-KidLearn** as the identity provider,
so parents can sign in with their existing See-KidLearn account and this app can read
their profile and (optionally) their children's profiles.

## 1. Credentials (ask the operator for these — do not invent them)

| Env var | Example | Notes |
|---|---|---|
| SEEKIDLEARN_ISSUER | https://see-kidlearn.com | Web origin; hosts the consent screen |
| SEEKIDLEARN_API | https://api.see-kidlearn.com/api/v1 | API origin; hosts token/userinfo |
| SEEKIDLEARN_CLIENT_ID | skl_xxxxxxxx… | Public identifier |
| SEEKIDLEARN_CLIENT_SECRET | sklsec_xxxxxxxx… | SERVER ONLY. Never ship to the browser. |
| SEEKIDLEARN_REDIRECT_URI | https://your-app.com/api/auth/seekidlearn/callback | Must match the registered value byte for byte |

Discovery document: `GET {SEEKIDLEARN_ISSUER}/.well-known/openid-configuration`

## 2. Endpoints

| Purpose | Method + URL |
|---|---|
| Authorization (browser redirect) | `GET {ISSUER}/oauth/authorize` |
| Token | `POST {API}/oauth/token` |
| User info | `GET {API}/oauth/userinfo` |
| Children list | `GET {API}/oauth/children` (needs `children:read`) |
| Introspect | `POST {API}/oauth/introspect` |
| Revoke | `POST {API}/oauth/revoke` |
| Register a user (first-party only) | `POST {API}/oauth/register-user` |
| Child sign-in (games) | `POST {API}/oauth/token` with the child-password grant |
| Profile re-sync (first-party only) | `GET {API}/oauth/users/{sub}` |
| Changed-user feed (first-party only) | `GET {API}/oauth/users?updated_since={iso}` |
| Parent profile picture (public image, no auth) | `GET {API}/avatars/{sub}/{sig}` — take the URL from the `picture_or_default` claim, never build it (§3c) |
| Default picture (placeholder) | `GET {API}/avatars/default?seed={any}` |

## 3. Scopes → exact claim names

Claim names follow **OIDC Core 1.0 §5.1**. Code against these spellings, not the
scope names — in particular the phone claim is `phone_number`, **not** `phone`.

| Scope | Claims it adds to `/oauth/userinfo` |
|---|---|
| `openid` | (required for an `id_token`; adds no claim of its own) |
| `profile` | `name`, `given_name`, `family_name`, `picture`, `picture_or_default`, `locale`, `role`, `created_at` |
| `email` | `email`, `email_verified` |
| `phone` | `phone_number`, `phone_number_verified` |
| `subscription:read` | `subscription` (object, or `null`) |
| `children:read` | nothing in userinfo — unlocks `GET /oauth/children` |
| `child:profile` | a CHILD's own profile; only ever issued by the child-password grant |

`sub`, `sub_type` and `updated_at` are always present, whatever the scope.

Request only what you actually use. Anything outside the client's registered
allow-list is silently dropped.

### Which claims can be missing, and when

The rule is: **if the scope was granted, the key is always present.** A value the
parent never filled in comes back as `null` — never as an absent key. So
`"phone_number" in profile === false` means *you did not get the `phone` scope*,
while `profile.phone_number === null` means *this parent has no phone on file*.

| Claim | When it is `null` / absent |
|---|---|
| `phone_number` | `null` if the parent never entered a phone. **Absent** only if `phone` was not granted. |
| `phone_number_verified` | `false` when unverified — the number is **still returned**. Never null. |
| `email_verified` | `false` until the parent clicks the verification link. See-KidLearn does not force verification, so plenty of live accounts sit at `false`. |
| `picture` | `null` if the parent has no photo — never uploaded one and has no Google/Facebook/LINE picture. See §3c. |
| `picture_or_default` | **never null** — always an image URL (the photo, or a default picture). See §3c. |
| `given_name`, `family_name` | `null` if unset |
| `name` | `""` if the parent has neither a display name nor a first/last name |
| `locale` | never null — defaults to `"th"` |
| `subscription` | `null` if the parent has no subscription record at all |
| everything else | absent if its scope was not granted |

Treat every claim except `sub`, `sub_type`, `updated_at`, `locale` and
`picture_or_default` as nullable in your types. Do not make an unverified phone or
email a hard failure.

## 3b. Full `/oauth/userinfo` response (parent token)

Granted `openid profile email phone subscription:read children:read`. Values are
masked; **every field name that can appear is shown**:

```http
GET {API}/oauth/userinfo
Authorization: Bearer {access_token}
```

```json
{
  "sub": "660a1b2c3d4e5f6071829304",
  "sub_type": "user",
  "updated_at": "2025-09-02T04:30:11.421Z",

  "name": "สมชาย ใจดี",
  "given_name": "สมชาย",
  "family_name": "ใจดี",
  "picture": "https://api.see-kidlearn.com/api/v1/avatars/660a1b2c3d4e5f6071829304/k3Jd9QxPz2LmN8vT4wYb1A?v=3f9a1c7b2e",
  "picture_or_default": "https://api.see-kidlearn.com/api/v1/avatars/660a1b2c3d4e5f6071829304/k3Jd9QxPz2LmN8vT4wYb1A?v=3f9a1c7b2e",
  "locale": "th",
  "role": "parent",
  "created_at": "2025-01-05T09:12:44.000Z",

  "email": "somchai@example.com",
  "email_verified": true,

  "phone_number": "0812345678",
  "phone_number_verified": false,

  "subscription": {
    "status": "trial",
    "package_slug": "basic",
    "expires_at": "2025-10-01T00:00:00.000Z"
  }
}
```

`children:read` adds nothing here — it unlocks `GET /oauth/children` (§5).
`role` is one of `parent` | `admin` | `super_admin`.
`subscription.status` is one of `trial` | `active` | `expired` | `cancelled` | `blocked`.

## 3c. Parent profile picture

Parents can upload a profile photo on see-kidlearn (Settings → Profile). It is
cropped to a square (1:1) and stored as a 512×512 JPEG. Every parent — with a
photo or without — has ONE public picture URL:

```
{API}/avatars/{sub}/{sig}?v={version}
```

It arrives as the `picture_or_default` claim (scope `profile`) in
`/oauth/userinfo`, `GET /oauth/users/{sub}` and the `id_token`. **Take the URL from
the claim — never build it yourself.** `{sig}` is an HMAC only see-kidlearn can
compute, so a guessed or hand-built URL answers `404`.

The two claims:

| Claim | Value | Use it to |
|---|---|---|
| `picture` | The parent's real picture URL, or `null` when they have none | decide "does this parent have a photo?" |
| `picture_or_default` | Never null. The URL above: the photo, or a default picture | display — put it straight into `<img src>` |

What the URL returns — no auth header, works from any origin:

| Situation | Response | `X-Avatar-Source` header |
|---|---|---|
| Parent uploaded a photo | `200`, `image/jpeg` (png/webp possible), 512×512 | `upload` |
| No upload, but they signed up with Google / Facebook / LINE | `302` redirect to that picture | `social` |
| Neither — or the account is deleted / suspended | `200`, `image/png` 256×256: white head-and-shoulders silhouette on a colour picked from the `sub` | `default` |
| `sig` wrong or missing, `sub` malformed | `404` JSON | — |

Freshness and caching:

- `?v=` changes every time the parent uploads a new photo. With the current `v`
  the image is sent `Cache-Control: public, max-age=31536000, immutable`; without
  `v` (or with an old one) `max-age=300`. `ETag` / `If-None-Match` → `304` works.
- Uploading or removing a photo bumps the user's `updated_at`, so the changed-user
  feed (§4b) reports the parent. Re-read the profile and store the new
  `picture_or_default` — the path stays the same, only `v` moves.
- Prefer linking to the URL over downloading and re-hosting the image. If you
  must keep a copy, fetch it server-side and key your copy on `v`.
- Served with `Cross-Origin-Resource-Policy: cross-origin`, so `<img>` works on any
  site. Reading the bytes with `fetch()` from browser JS is a CORS request — do that
  server-side instead.

Rendering: the image is square, so show it with `object-fit: cover` in a circle
or rounded square. Every response is JPEG/PNG/WebP, never SVG. Simplest is a
plain `<img>`. With Next.js `next/image`, either set `unoptimized`, or add
`api.see-kidlearn.com` (pathname `/api/v1/avatars/**`) to `images.remotePatterns`
**and** the social hosts (`lh3.googleusercontent.com`,
`profile.line-scdn.net`, `platform-lookaside.fbsbx.com`) — a social picture
reaches you through a 302 to one of those.

A default picture on its own, for a placeholder before anyone signs in:
`GET {API}/avatars/default?seed={anything}` (same style, colour picked from `seed`).

Privacy: the URL is unguessable but public — anyone holding it can see the photo.
Treat it like the photo itself: show it only where the parent would expect their
photo, and delete your copy with the rest of the account (§4c).

A child token is unaffected: its `picture` is still the child's avatar (§6).

## 4. Flow to implement — Authorization Code + PKCE (S256)

### Step A — start login (`GET /api/auth/seekidlearn/login`)

1. `code_verifier` = 64 random bytes, base64url, no padding (43–128 chars).
2. `code_challenge` = base64url(SHA-256(code_verifier)), no padding.
3. `state` = 32 random bytes, base64url. `nonce` = 32 random bytes, base64url.
4. Store `code_verifier`, `state`, `nonce` in an **httpOnly, Secure, SameSite=Lax**
   cookie (or server session) with a 10-minute TTL.
5. Redirect the browser to:

```
{ISSUER}/oauth/authorize
  ?response_type=code
  &client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}   (URL-encoded)
  &scope=openid%20profile%20email
  &state={state}
  &nonce={nonce}
  &code_challenge={code_challenge}
  &code_challenge_method=S256
```

At the consent screen the parent may sign in with email/password **or with
Google, Facebook or LINE** — whichever they already use on see-kidlearn. Either
way they come back to your `redirect_uri` with the same `?code=`, so there is
nothing extra to implement for social sign-in.

### Step B — callback (`GET /api/auth/seekidlearn/callback`)

1. If the query contains `error`, render that error — do not continue.
   `error=access_denied` simply means the parent pressed "ไม่อนุญาต".
2. Compare the returned `state` with the stored one using a constant-time
   comparison. Mismatch → abort (CSRF).
3. Exchange the code (server-side, never from the browser):

```http
POST {API}/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})

grant_type=authorization_code
&code={code}
&redirect_uri={REDIRECT_URI}
&code_verifier={code_verifier}
```

Response:

```json
{
  "access_token": "…",      // opaque, ~1 hour
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",      // opaque, ~30 days, single-use (rotates)
  "scope": "openid profile email",
  "id_token": "eyJ…"         // JWT, HS256, signed with YOUR client secret
}
```

4. Verify `id_token` with HS256 using `SEEKIDLEARN_CLIENT_SECRET` and check
   `iss === SEEKIDLEARN_ISSUER`, `aud === CLIENT_ID`, `exp` in the future, and
   `nonce` equal to the stored nonce.
5. `GET {API}/oauth/userinfo` with `Authorization: Bearer {access_token}` to get
   the canonical profile. Exact claim names are in §3; the full response is §3b.
6. Upsert a local user keyed on `sub` (the See-KidLearn user id). **Key on `sub`,
   never on email** — an email can change. Store the returned `updated_at` too;
   the sync in §4b uses it.
7. Create this app's own session (its own cookie/JWT). Store the See-KidLearn
   `access_token` / `refresh_token` encrypted, server-side only.
8. Delete the PKCE cookie and redirect the user into the app.

### Step C — refresh

```http
POST {API}/oauth/token
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})
grant_type=refresh_token&refresh_token={refresh_token}
```

Refresh tokens **rotate**: every refresh returns a new one and invalidates the
old. Persist the new pair atomically. If you replay an old refresh token the
provider revokes the whole family and the user must sign in again — so never
refresh concurrently from two places.

### Step D — logout

`POST {API}/oauth/revoke` with `token={refresh_token}` and Basic auth, then clear
this app's session. It always returns 200.

## 4b. Keeping the local copy fresh (first-party clients)

`/oauth/userinfo` is a snapshot at the moment you call it. If you only call it in
the callback, your copy of the parent's phone, email and name goes stale the
moment they edit it on see-kidlearn — and if your own session is long-lived, they
may never sign in again to refresh it. **Do not rely on re-login for freshness.**

Two client-authenticated endpoints exist for this. Both use HTTP Basic with the
client credentials — no user access token — and both are restricted to
**confidential first-party** clients; anyone else gets `403 unauthorized_client`.

Check that your client actually carries the flag before building against these:
`GET {API}/oauth/client-info?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}` is
public and returns `data.is_first_party`. If it is `false`, ask the See-KidLearn
operator to tick it — no amount of retrying will get past the 403.

### Re-read one profile

```http
GET {API}/oauth/users/{sub}
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})
```

Returns exactly the `/oauth/userinfo` claim set for the scopes **that user has
currently granted your client**, plus `status` and the `scope` string so you can
see what you were allowed to read:

```json
{
  "sub": "660a1b2c3d4e5f6071829304",
  "sub_type": "user",
  "updated_at": "2025-09-02T04:30:11.421Z",
  "name": "สมชาย ใจดี",
  "given_name": "สมชาย",
  "family_name": "ใจดี",
  "picture": "https://api.see-kidlearn.com/api/v1/avatars/660a1b2c3d4e5f6071829304/k3Jd9QxPz2LmN8vT4wYb1A?v=3f9a1c7b2e",
  "picture_or_default": "https://api.see-kidlearn.com/api/v1/avatars/660a1b2c3d4e5f6071829304/k3Jd9QxPz2LmN8vT4wYb1A?v=3f9a1c7b2e",
  "locale": "th",
  "role": "parent",
  "created_at": "2025-01-05T09:12:44.000Z",
  "email": "somchai@example.com",
  "email_verified": true,
  "phone_number": "0812345678",
  "phone_number_verified": false,
  "status": "active",
  "scope": "openid profile email phone"
}
```

`404 no_grant` means there is no live grant: the user never connected, revoked
your app, or their refresh token expired. Stop syncing that user.

**The `scope` in the response is that USER's grant, not your client's allow-list.**
A user who last authorized before a scope was added to your client gets a profile
without it, and refreshing cannot widen a token's scope — only a fresh trip through
`/oauth/authorize` can. So if `phone` was granted to your client recently, expect a
period where new sign-ins carry it and older sessions do not, and no amount of
syncing will backfill them.

Detect it by reading `scope` on every sync response rather than assuming it. If a
scope you need is missing for a user, the only fix is to send them through the
authorization flow again — decide deliberately whether that is worth prompting for,
and never treat it as a transient error to retry.

### The changed-user feed

Polling every user one by one does not scale. Ask for the ones that changed:

```http
GET {API}/oauth/users?updated_since=2025-09-01T00:00:00.000Z&limit=100
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})
```

```json
{
  "updated_since": "2025-09-01T00:00:00.000Z",
  "limit": 100,
  "count": 2,
  "has_more": false,
  "next_updated_since": "2025-09-02T04:30:11.421Z",
  "users": [
    { "sub": "660a…", "status": "active",  "updated_at": "2025-09-01T22:10:02.000Z",
      "deleted_at": null, "purge_at": null },
    { "sub": "661b…", "status": "deleted", "updated_at": "2025-09-02T04:30:11.421Z",
      "deleted_at": "2025-09-02T04:30:11.421Z", "purge_at": "2025-10-02T04:30:11.421Z" }
  ]
}
```

Only `sub` + lifecycle come back — no personal data — so this response is safe to
log. `limit` defaults to 100 and is capped at 200.

How to run the sync:

1. Store a `last_synced_at` watermark. Start it at the time you go live.
2. Call the feed with `updated_since=last_synced_at`.
3. For each row: `status: "active"` → `GET /oauth/users/{sub}` and update your copy.
   Anything else → apply §6.
4. Save `next_updated_since` as the new watermark. While `has_more` is true, call
   again with `next_updated_since` before saving it.
5. Every 15–60 minutes is plenty. There is no push/webhook channel today.

Both endpoints share a budget of 600 requests per 5 minutes per client. That is far
more than a normal sync needs; on `slow_down` (429) honour `Retry-After` and resume
from the watermark you last saved.

`updated_at` is bumped by **any** write to the user document, not only the fields
you care about, so the feed over-reports rather than under-reports. Treat a row as
"re-read this one", never as proof that a specific field changed. Diff against your
own copy before acting — otherwise you will send "your phone number changed" mail
to people whose phone number did not change.

## 4c. Deleted and suspended accounts

A parent can delete their See-KidLearn account, or an admin can suspend it. Either
way **your tokens do not fail immediately** — an already-issued access token stays
within its lifetime — so you must check the account state, not just the token.

Three places report it:

| Where | What you get |
|---|---|
| `GET /oauth/users/{sub}` | `status`, and for a deletion `deleted_at` + `purge_at` |
| `GET /oauth/users?updated_since=` | the same, for every changed user at once |
| `POST /oauth/introspect` | `account_status`, `account_deleted_at`, `account_purge_at` |

```json
// GET /oauth/users/{sub} for a deleted account — NO personal claims are returned
{
  "sub": "661b…",
  "status": "deleted",
  "purged": false,
  "scope": "openid profile email phone",
  "updated_at": "2025-09-02T04:30:11.421Z",
  "deleted_at": "2025-09-02T04:30:11.421Z",
  "purge_at": "2025-10-02T04:30:11.421Z"
}
```

`status` / `account_status` values:

- `active` — normal.
- `suspended` — blocked or deactivated by an admin. Reversible: block sign-in and
  hide the account, but keep the data; it may come back.
- `deleted` — the parent asked for deletion. See-KidLearn soft-deletes and purges
  for good at `purge_at` (30 days later). **That window is your PDPA deadline:**
  cancel or hand off their pending bookings, then delete or anonymise your copy by
  `purge_at` at the latest.
- `purged` — the user document is gone. Nothing left to reconcile; delete your copy
  now. (`GET /oauth/users/{sub}` answers with `"status": "deleted", "purged": true`.)

On `POST /oauth/introspect`, note that **`active` describes the TOKEN, not the
account** (RFC 7662). A token can be `"active": true` while `account_status` is
`"deleted"`. Gate access on `account_status`:

```json
{
  "active": true,
  "scope": "openid profile email phone",
  "client_id": "skl_…",
  "token_type": "Bearer",
  "sub": "660a…",
  "sub_type": "user",
  "account_status": "active",
  "exp": 1735689600,
  "iat": 1735686000,
  "iss": "https://see-kidlearn.com"
}
```

For a child token `sub` is the owning **parent** and the player is `child_sub`,
with `sub_type: "child"`. `account_status` then describes the parent account.

Meanwhile `/oauth/userinfo` and `/oauth/children` answer `401 invalid_token` for a
suspended or deleted account, so treat that 401 as "stop", not as "retry".

## 5. Reading children (optional)

```http
GET {API}/oauth/children
Authorization: Bearer {access_token}
```

Full response — every field name that can appear:

```json
{
  "sub": "660a1b2c3d4e5f6071829304",
  "children": [
    {
      "id": "665f1a2b3c4d5e6f70819203",
      "nickname": "น้องไอซ์",
      "avatar_id": "bear",
      "avatar_url": "https://cdn.see-kidlearn.com/avatars/bear.png",
      "date_of_birth": "2020-04-11T00:00:00.000Z",
      "gender": "female",
      "grade_id": "6612aa…",
      "total_stars": 120,
      "streak_days": 3,
      "last_played_at": "2025-09-01T11:02:33.000Z",
      "created_at": "2025-01-05T09:20:00.000Z"
    }
  ]
}
```

Nullable here: `avatar_url`, `date_of_birth`, `gender`, `grade_id`,
`last_played_at` — all of them are optional in a child profile. Only active
children are listed, and `game_password` / `pin` are never returned.

Returns 403 `insufficient_scope` if `children:read` was not granted. Children data
concerns minors: store the minimum you need, never expose it to other users, and
delete it when the parent disconnects.

## 6. Child sign-in for games (only if the client has `allow_child_login`)

For a kids' game the player is the CHILD, not the parent. Every child profile in
see-kidlearn has a 5-character game password (e.g. `K7M2Q`) the parent can see
and regenerate in their dashboard. Exchange it for a child-scoped token:

```http
POST {API}/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})

grant_type=urn:see-kidlearn:params:oauth:grant-type:child-password
&game_password=K7M2Q
&scope=openid child:profile
```

(`grant_type=child_password` is accepted as a shorter alias.)

Returns the normal token payload — `access_token`, `refresh_token`, `expires_in`
— but **no `id_token`**, because the subject is a child, not an OIDC end user.

`GET {API}/oauth/userinfo` with that token returns the child, not the parent:

```json
{
  "sub": "665f1a2b3c4d5e6f70819203",
  "sub_type": "child",
  "parent_sub": "660a1b2c3d4e5f6071829304",
  "nickname": "น้องไอซ์",
  "avatar_id": "bear",
  "picture": "https://cdn.see-kidlearn.com/avatars/bear.png",
  "date_of_birth": "2020-04-11T00:00:00.000Z",
  "gender": "female",
  "grade_id": "6612aa…",
  "total_stars": 120,
  "total_score": 4820,
  "streak_days": 3,
  "locale": "th",
  "parental_control": {
    "daily_time_limit_minutes": 60,
    "allowed_start_time": "08:00",
    "allowed_end_time": "20:00",
    "used_minutes_today": 25,
    "remaining_minutes": 35
  }
}
```

Nullable: `picture`, `date_of_birth`, `gender`, `grade_id`. Without the
`child:profile` scope the same call returns only
`{ "sub", "sub_type": "child", "parent_sub" }` — identity and nothing else.
There is no `email`, `phone_number` or `subscription` on a child token, ever.

Rules for this grant:

- The client must be confidential and flagged `allow_child_login`; otherwise the
  provider answers `unauthorized_client`. The call is server-side only.
- The token carries **only** `openid` and `child:profile`. It cannot read the
  parent's email, phone, subscription or the sibling list — `/oauth/children`
  returns 403 for it.
- **Honour `parental_control`**: refuse to start play outside
  `allowed_start_time`–`allowed_end_time`, and stop at `remaining_minutes` = 0.
  Re-read `/oauth/userinfo` periodically; the counters are live.
- Child sign-in is rate limited harder than other grants (a 5-char password is
  brute-forceable). On `slow_down` (429) back off — do not retry in a loop.
- Never store the game password. Keep the tokens server-side, key the game
  session on `sub`.

## 7. First-party mode (only if the operator says this client is first-party)

A first-party client may host its own login/register form instead of redirecting:

```http
POST {API}/oauth/token
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})
grant_type=password&username={email}&password={password}&scope=openid profile email
```

```http
POST {API}/oauth/register-user
Authorization: Basic base64({CLIENT_ID}:{CLIENT_SECRET})
Content-Type: application/json

{ "email": "...", "password": "...", "first_name": "...", "last_name": "...",
  "phone": "0812345678", "language": "th" }
```

`register-user` returns the same token payload as the token endpoint, so the new
parent lands signed in. 409 `account_exists` means "send them to login instead".
Both calls MUST be made from your server. If the client is not flagged
first-party the provider answers 400/403 `unauthorized_client` — use the redirect
flow instead.

## 8. Errors

Errors follow RFC 6749: `{ "error": "...", "error_description": "..." }`.

| error | Meaning / fix |
|---|---|
| invalid_client | Wrong client_id/secret, or client disabled |
| invalid_grant | Code or refresh token expired, already used, or redirect_uri mismatch |
| invalid_request | Missing parameter, or PKCE required but no code_challenge |
| unauthorized_client | This grant type is not enabled for the client |
| invalid_scope | Requested scope not in the client's allow-list |
| insufficient_scope | Endpoint needs a scope the token lacks (403) |
| slow_down | Token endpoint rate limit (429); honour `Retry-After` |
| invalid_grant (child) | Wrong game password, or the parent account is suspended |
| no_grant | `GET /oauth/users/{sub}` (404): no live grant — never connected, revoked, or expired. Stop syncing that user. |
| unauthorized_client (sync) | `/oauth/users…` on a client that is not confidential + first-party (403) |
| invalid_token (401 on userinfo) | Token expired or revoked, **or** the account is suspended/deleted. Do not retry blindly — introspect to tell the two apart. |

## 9. Hard requirements

- The client secret, the token exchange, and the refresh call are **server-side only**.
- `redirect_uri` must match the registered value exactly — no trailing slash drift.
- Always send PKCE S256; always verify `state`.
- Store See-KidLearn tokens encrypted at rest; never in `localStorage`.
- Key local accounts on `sub`.
- The access token is opaque — do not try to decode it. Only `id_token` is a JWT.
- On `invalid_grant` during refresh, clear the local session and restart the login flow.
- A child token is not a parent token: check `sub_type` before assuming which one you hold.
- Do not treat the callback's `/oauth/userinfo` as permanently correct. Re-sync on a
  schedule (§4b) — a long-lived session means the user may never sign in again.
- Type every claim as nullable except `sub`, `sub_type`, `updated_at`, `locale` and
  `picture_or_default`. Read the phone as `phone_number`, not `phone`.
- Display the parent's picture from `picture_or_default` exactly as given — never
  construct an avatar URL (§3c).
- Gate access on `account_status`, not on introspect's `active` (§4c), and honour
  `purge_at` on a deleted account.

## 10. Deliverables

1. `GET /api/auth/seekidlearn/login` — builds PKCE + state and redirects.
2. `GET /api/auth/seekidlearn/callback` — validates, exchanges, upserts, creates a session.
3. A token-refresh helper used by every outbound call, handling rotation.
4. `POST /api/auth/logout` — revokes the refresh token and clears the session.
5. A "Sign in with See-KidLearn" button on the login page.
6. `.env.example` with the five variables above, and a README section covering setup.
7. A scheduled profile sync (first-party clients): reads
   `GET /oauth/users?updated_since=`, re-reads each changed `active` user via
   `GET /oauth/users/{sub}`, and persists the `last_synced_at` watermark.
8. Account-lifecycle handling: `suspended` → block sign-in and hide the account;
   `deleted` → cancel or hand off pending work and erase your copy by `purge_at`;
   `purged` / `no_grant` → erase now and stop syncing.
9. The parent's picture wherever the app shows the signed-in parent (header,
   profile, booking lists): `<img src={picture_or_default}>`, square image shown
   round with `object-fit: cover`, refreshed by the profile sync.
10. Tests for: PKCE generation, state mismatch rejection, id_token verification,
   refresh rotation, the sync watermark advancing correctly across `has_more`
   pages, and each account status driving the right local action.

Use the language, framework and conventions already present in this repository.
Do not add an OAuth library unless the repo already depends on one.