46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
|
# ADR-003: Identity Context Ownership
|
||
|
|
|
||
|
|
**Status:** Accepted
|
||
|
|
**Date:** 2026-03-18
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Global ADR-003 establishes that context helpers must live with their data owners.
|
||
|
|
`Identity` is defined in the `rbac` package. Its context key, storage function, and
|
||
|
|
retrieval function must also live here to avoid requiring any other package to know
|
||
|
|
the key type.
|
||
|
|
|
||
|
|
If the context key for `Identity` were defined elsewhere (e.g. in an `httpauth`
|
||
|
|
module), any package that wanted to retrieve an identity from context would need to
|
||
|
|
import `httpauth` — creating a coupling that does not make sense for packages that
|
||
|
|
have nothing to do with HTTP authentication.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
The unexported type `authContextKey struct{}` and the package-level variable
|
||
|
|
`authKey = authContextKey{}` are defined in `identity.go` within the `rbac` package.
|
||
|
|
Two exported functions manage the context lifecycle:
|
||
|
|
|
||
|
|
- `SetInContext(ctx context.Context, id Identity) context.Context` — stores the
|
||
|
|
identity value under `authKey`.
|
||
|
|
- `FromContext(ctx context.Context) (Identity, bool)` — retrieves it, returning
|
||
|
|
`false` when absent.
|
||
|
|
|
||
|
|
The key type is unexported (`authContextKey`), which prevents any external package
|
||
|
|
from constructing or comparing the key directly — only `rbac` can write or read the
|
||
|
|
identity in context. This eliminates the risk of key collisions with other packages
|
||
|
|
that might also use an empty struct as a context key.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
- Any package that needs to read the authenticated identity imports only `rbac` —
|
||
|
|
not `httpauth`, not any HTTP package.
|
||
|
|
- `httpauth` middleware stores the identity via `rbac.SetInContext`; domain handlers
|
||
|
|
retrieve it via `rbac.FromContext`. The two call sites share a single, well-known
|
||
|
|
contract.
|
||
|
|
- The unexported key type guarantees that no external package can accidentally shadow
|
||
|
|
or overwrite the identity value by using the same key.
|
||
|
|
- `PermissionProvider.ResolveMask` receives `ctx` explicitly; implementations that
|
||
|
|
need the `TenantID` call `rbac.FromContext(ctx)` to obtain it — no need to thread
|
||
|
|
tenant ID as a separate parameter.
|