# Mission — Authentication & Authorization in *this* repo

## Who this is for
A backend engineer in this monorepo who wants to genuinely understand how the platform answers the
two security questions — **"who are you?"** (authentication) and **"what may you do?"**
(authorization) — end to end, and to be **interview-ready** on the techniques it uses.

Strong backend maturity (this is far from their first course). **Newer to this repo's auth/authz
machinery**: the JWT flow, the Shamir token authority, the gRPC auth interceptor, `rbacDecider`, the
granular permission/role model, locations & `access_paths`, Postgres Row-Level Security, and how
`resource_path` threads organization multi-tenancy through all of it.

## The mission
> *"Research this codebase carefully and teach me everything about its authentication and
> authorization techniques — roles, permissions, locations, access_paths, RLS, RBAC, organizations —
> so I can catch up on the repo and prepare for the interview."*

Two concrete targets:
1. **Catch-up fluency** — open any endpoint and know exactly how a request is authenticated, which
   role gate it passes, whether it's permission- or location-scoped, and how RLS isolates the tenant.
2. **Interview readiness** — whiteboard "how does an authenticated, authorized request reach the
   database?" and defend the design (JWT/JWKS, token exchange, RBAC vs ABAC, RLS vs app-layer checks,
   defense in depth, service-to-service auth).

## The lead focus (chosen by the learner)
**Balanced, end-to-end** — trace one request through *every* gate: token → interceptor (verify +
claims) → `rbacDecider` (role gate) → service-layer ownership/permission check → granted permissions
scoped by **location subtree** → repo (`WHERE resource_path`, `deleted_at IS NULL`) → **RLS** at the
database. No single tier gets all the weight; the *chain* is the subject.

## The anchor (chosen by the learner)
**The usermgmt / golibs / shamir core** — where authentication, roles, permissions, locations, and
RLS are actually *defined and managed*: `internal/golibs/interceptors`,
`internal/usermgmt/pkg/interceptors`, `internal/shamir`, `internal/usermgmt/...`, and the
`migrations/auth` + `migrations/bob` RLS/permission schema. Not a per-service tour.

## What "done" looks like
- Can name the **two security questions** and the **layers** that answer each: JWKS-verified JWT
  (authN); `rbacDecider` role gate + granular permission/location model + RLS (authZ).
- Can explain what's **inside a Manabie JWT** (the `Manabie` claim) and how **Shamir** mints it
  (verify external token → look up user → sign a new Manabie token) and hosts the **JWKS**.
- Can read `rbacDecider` and state the exact semantics (role list / `nil` / **absent → runtime
  `PermissionDenied`**, *not* a startup panic — correcting the docs).
- Can trace a **permission** (`user.user.read`) from `permission` → `role` → `user_group` → a user,
  **scoped to a location subtree** via `access_path` and `granted_role_access_path`.
- Can explain **RLS**: `resource_path` = org; `setPostgres` sets session vars from the JWT on every
  connection acquire; `permission_check()` enforces tenant isolation; location-aware policies combine
  tenant + `app.user_id` + granted permissions.
- Can articulate **defense in depth**: what the interceptor, the service check, and RLS each catch
  that the others miss.

## Non-goals
- Not a Go/gRPC course (those exist). This is about the **security machinery**, not the language.
- Not a per-service tour — the core is taught once and generalizes to every service.
- Not exhaustive of every edge (Salesforce, Auth0, JPREP division checks) — named where relevant,
  taught only as far as the core flow needs.