# middleware/context-augmentation

## Purpose

This module installs the canonical Hono `ContextVariableMap`
augmentation that lets every consumer call `c.get("user")` and
`c.get("session")` with full type narrowing. Without this declaration
those calls would resolve to `unknown`, forcing every plugin to cast at
the call site.

## Features

- Declares `user: Principal | null` and `session: BetterAuthSessionResult`
  on Hono's global `ContextVariableMap` interface.
- Side-effect-only export — importing the module wires the augmentation
  into TypeScript's global module registry.
- Re-exported transitively via every middleware module so consumers
  importing any auth middleware automatically inherit the augmentation.

## Usage: Basic

```ts
import "@suaveplan/api-plugin-auth/middleware/session";
// or
import "@suaveplan/api-plugin-auth";

// c.get("user") now narrows to Principal | null everywhere.
```

## Usage: Advanced

Combine the augmentation with `requireAuth()` so downstream handlers
get a non-null `Principal` directly. The type system cannot prove the
narrowing through a middleware chain, but explicit destructuring keeps
the call site clean:

```ts
import { requireAuth } from "@suaveplan/api-plugin-auth/middleware";

app.use("/me", requireAuth());
app.get("/me", (c) => {
    const principal = c.get("user");
    if (principal === null) throw new Error("unreachable");
    return c.json({ id: principal.id });
});
```

## API Reference

### Module augmentation

```ts
declare module "hono" {
    interface ContextVariableMap {
        user: Principal | null;
        session: BetterAuthSessionResult;
    }
}
```

The module exports `export {}` — there are no runtime exports, only the
ambient declaration.

## Implementation Notes

- The augmentation is intentionally re-exported as a side effect from
  every middleware module's barrel so a single
  `import "@suaveplan/api-plugin-auth"` is enough to enable the typed
  context everywhere — no separate "augmentation" import is needed.
- `session` is typed as the `BetterAuthSessionResult` (a `| null`
  union) rather than the bare `BetterAuthSessionView` so anonymous
  contexts type-check without a cast.
- Augmenting third-party type definitions is the standard pattern for
  Hono plugins; the auth plugin owns these two slots and no other
  plugin should re-declare them. Sibling plugins layer their own slots
  via additional augmentations.