# AAuth Demo UI

This directory contains the interactive UI demo work for the AAuth protocol described in [UI-DEMO-PLAN.md](../UI-DEMO-PLAN.md).

It has two parts:

- `backend/generate.py`
  Generates JSON scenario fixtures using the real `aauth` Python library.
- `frontend/`
  Next.js app that renders the scenarios with sequence diagrams, token viewers, header inspectors, and mission/deferred-auth visualizations.

This README is the handoff document for resuming work later.

## Current Status

The UI exists and is runnable. We paused after implementing and reviewing these plan items:

- Phase 1: Pseudonymous signing
- Phase 2: Agent identity via JWKS
- Phase 3: Federated / autonomous access
- Phase 4: User delegation with deferred `202 -> 202 -> 200` flow
- Phase 5.1: Mission proposal and approval
- Phase 5.2: Proactive authorization with mission context

These were not just scaffolded; they were actively corrected against `UI-DEMO-PLAN.md` in this workspace.

We paused before continuing to:

- Phase 6: Agent delegation
- Phase 7: Call chaining
- Phase 8: Clarification chat
- Phase 9: Interaction chaining
- Phase 10: Proactive authorization polish / comparison work
- Phase 11: PS-AS federation trust review
- Phase 12: End-to-end mission lifecycle review
- Compare pages beyond the light cleanup already done

Important nuance:

- Many later routes and fixtures already exist in the tree.
- They were present before this pause, but not all of them have been audited against the plan with the same rigor as Phases 1 through 5.2.

## Start The UI

From the repo root:

```bash
cd /Users/christian.posta/Dropbox/postamac-share/dev/code/aauth
```

Install frontend dependencies if needed:

```bash
cd aauth-demo-ui/frontend
npm install
```

Run the UI:

```bash
npm run dev
```

Open:

```text
http://localhost:3000
```

## Regenerate Scenario Fixtures

Scenario data is generated by:

- [backend/generate.py](./backend/generate.py)

It writes JSON files to:

- `aauth-demo-ui/frontend/lib/scenarios/`

Use the repo virtualenv so the local `aauth` package and Python dependencies are available:

Generate all fixtures:

```bash
./.venv/bin/python aauth-demo-ui/backend/generate.py
```

Generate one scenario:

```bash
./.venv/bin/python aauth-demo-ui/backend/generate.py --scenario federated
./.venv/bin/python aauth-demo-ui/backend/generate.py --scenario user-delegation
./.venv/bin/python aauth-demo-ui/backend/generate.py --scenario missions-lifecycle
./.venv/bin/python aauth-demo-ui/backend/generate.py --scenario missions-proactive-authz
```

## Validate The Frontend

From `aauth-demo-ui/frontend`:

```bash
npm run lint
```

At the point we paused, lint was clean.

## Main UI Routes

Current route inventory:

### Signing

- `/signing/pseudonymous`
- `/signing/identity`
- `/signing/compare`

### Access

- `/access/identity-based`
- `/access/federated`
- `/access/user-delegation`
- `/access/ps-managed`
- `/access/compare`

### Missions

- `/missions/lifecycle`
- `/missions/proactive-authz`
- `/missions/end-to-end`
- `/missions/compare`

### Advanced

- `/advanced/delegation`
- `/advanced/call-chaining`
- `/advanced/clarification`
- `/advanced/interaction-chaining`

## Demos Worth Exercising Right Now

If you want the shortest manual smoke test, use these in order:

1. `/signing/pseudonymous`
   Confirms the base scenario shell and HTTP signature visualizer.
2. `/signing/identity`
   Confirms JWKS identity flow and token/header inspection.
3. `/access/federated`
   Confirms the corrected 5-step Phase 3 flow and token lifecycle view.
4. `/access/user-delegation`
   Confirms the deferred authorization timeline (`202 -> 202 -> 200`).
5. `/missions/lifecycle`
   Confirms mission blob rendering and s256 verification chain.
6. `/missions/proactive-authz`
   Confirms mission claim propagation through resource token and auth token.

## What Was Corrected Before Pausing

These are the important corrections already made so the next session does not accidentally undo them.

### Phase 3

- `/access/federated` was corrected to match the planned 5-step flow.
- The auth token now includes an `act` claim.
- A reusable token lifecycle view was added.

Relevant files:

- [backend/generate.py](./backend/generate.py)
- [frontend/lib/scenarios/federated.json](./frontend/lib/scenarios/federated.json)
- [frontend/components/core/TokenFlowDiagram.tsx](./frontend/components/core/TokenFlowDiagram.tsx)

### Phase 4

- `/access/user-delegation` was expanded from a simplified flow to an explicit deferred flow.
- The scenario now shows:
  - AS deferred response
  - propagated pending URL and interaction URL
  - at least one `202` polling iteration before success
  - user consent step
  - later successful poll returning auth token
- A reusable deferred timeline component was added.

Relevant files:

- [backend/generate.py](./backend/generate.py)
- [frontend/lib/scenarios/user-delegation.json](./frontend/lib/scenarios/user-delegation.json)
- [frontend/components/core/DeferredResponseTimeline.tsx](./frontend/components/core/DeferredResponseTimeline.tsx)

### Phase 5.1

- `/missions/lifecycle` was upgraded from generic request/response rendering to mission-specific rendering.
- Mission blob, tool list, approver, s256, and capabilities are now explicit.
- A dedicated s256 chain visualization was added.

Relevant files:

- [frontend/components/core/MissionBlobViewer.tsx](./frontend/components/core/MissionBlobViewer.tsx)
- [frontend/components/core/S256ChainVisualization.tsx](./frontend/components/core/S256ChainVisualization.tsx)
- [frontend/lib/scenarios/missions-lifecycle.json](./frontend/lib/scenarios/missions-lifecycle.json)

### Phase 5.2

- `/missions/proactive-authz` was expanded to the planned 5-step shape.
- The mission claim now visibly propagates:
  - approved mission
  - `AAuth-Mission` header
  - resource token `mission` claim
  - auth token `mission` claim
  - final resource access verification

Relevant files:

- [backend/generate.py](./backend/generate.py)
- [frontend/lib/scenarios/missions-proactive-authz.json](./frontend/lib/scenarios/missions-proactive-authz.json)

### Navigation / Discovery Cleanup

- Landing page copy was corrected to align federated access vs PS-AS trust.
- Access comparison page was corrected so Phase 4 is described as user delegation, not a generic resource-managed mode.

Relevant files:

- [frontend/app/page.tsx](./frontend/app/page.tsx)
- [frontend/app/access/compare/page.tsx](./frontend/app/access/compare/page.tsx)

## Shared Components Added During This Work

These shared components now exist and should be reused rather than reinvented:

- `frontend/components/core/TokenFlowDiagram.tsx`
- `frontend/components/core/DeferredResponseTimeline.tsx`
- `frontend/components/core/MissionBlobViewer.tsx`
- `frontend/components/core/S256ChainVisualization.tsx`

The main scenario wrapper already knows how to render them when scenario JSON includes the corresponding fields:

- `token_flow`
- `deferred_timeline`
- `mission_blob`
- `s256_chain`

Relevant file:

- [frontend/components/scenarios/ScenarioPage.tsx](./frontend/components/scenarios/ScenarioPage.tsx)

## Where We Left Off Against UI-DEMO-PLAN.md

The plan file is:

- [../UI-DEMO-PLAN.md](../UI-DEMO-PLAN.md)

Best summary of actual progress:

- Phase 1: done and reviewed
- Phase 2: done and reviewed
- Phase 3: done and reviewed
- Phase 4: done and reviewed
- Phase 5.1: done and reviewed
- Phase 5.2: done and reviewed
- Phase 5.3: route exists, not yet reviewed in the same pass
- Phase 6+: routes/fixtures exist in many cases, but they have not all been reconciled to the plan after the Phase 3 to 5 work

If resuming later, the safest next step is:

1. Open `UI-DEMO-PLAN.md`.
2. Continue from the next unchecked phase, starting with Phase 6 `/advanced/delegation`, unless you decide to finish the mission track first by auditing `/missions/end-to-end`.
3. For any phase:
   - compare the plan entry to the route page and generated fixture
   - fix the generator first
   - regenerate the fixture
   - reuse shared visualization components where possible
   - run `npm run lint`

## Recommended Resume Order

Option A: Stay strictly phase-ordered

1. `/advanced/delegation`
2. `/advanced/call-chaining`
3. `/advanced/clarification`
4. `/advanced/interaction-chaining`
5. `/missions/end-to-end`
6. `/access/ps-managed`
7. compare pages and polish

Option B: Finish the missions track first

1. `/missions/end-to-end`
2. `/missions/compare`
3. `/advanced/delegation`
4. `/advanced/call-chaining`
5. `/advanced/clarification`
6. `/advanced/interaction-chaining`

## Notes

- The nested Git repo under `aauth-demo-ui/frontend/.git` was intentionally removed. Only the root repo should own version control.
- `frontend/README.md` is still the default Next.js boilerplate and is not the authoritative handoff document.
- This file is the authoritative resume point for the UI work.
