Add API token authorization TODO segments

2026-03-29 22:38:09 -07:00
parent caf4ec6266
commit f87b3f1989
1 changed files with 189 additions and 0 deletions
@@ -6,6 +6,195 @@ These segments are intended to be independently executable wherever possible.
 Each segment has its own local exit criteria.
 The product is not complete until the global exit criteria at the end of this file are also met.
 ## API Token And gRPC Authorization Parallel Segments
 These segments define the work for programmatic access control over gRPC.
 They are designed to be independently landable wherever file overlap permits.
 The feature is not complete until all segment exit criteria and the global exit criteria are satisfied.
 ### API Segment A: Token Domain Model
 Scope:
 - Represent API tokens as first-class vault-backed records.
 - Mark token entries explicitly as API credentials rather than generic passwords.
 - Store token metadata:
  token id,
  hashed secret or verifier,
  display name,
  client name,
  created at,
  expires at,
  disabled state.
 - Keep the persisted representation compatible with KDBX entry fields.
 Exit criteria:
 - A domain type exists for API tokens and round-trips through the persisted vault model.
 - Generic entry listing can distinguish API token entries from ordinary secrets.
 - Tests cover create, load, save, and parse behavior for API token entries.
 - `go test ./...` passes.
 ### API Segment B: Token Issuance And Rotation
 Scope:
 - Generate new API tokens for external tools.
 - Return the cleartext token only at creation or explicit rotation time.
 - Rotate an existing token while preserving its identity and policy linkage.
 - Revoke or disable a token without deleting policy history.
 Exit criteria:
 - Token issuance, rotation, disable, and revoke operations exist in the domain/service layer.
 - Cleartext token material is only exposed on creation or rotation paths.
 - Tests cover generation, rotation, and disable/revoke semantics.
 - `go test ./...` passes.
 ### API Segment C: Token Expiration
 Scope:
 - Allow tokens to have optional expiration timestamps.
 - Treat expired tokens as unauthenticated.
 - Surface expiration in UI and gRPC management views.
 - Support non-expiring tokens explicitly.
 Exit criteria:
 - Expired tokens are rejected by the gRPC authentication path.
 - Token expiration can be created, edited, and removed through the service layer.
 - Tests cover valid, expired, and non-expiring token behavior.
 - `go test ./...` passes.
 ### API Segment D: Authorization Policy Model
 Scope:
 - Define an authorization model for token-scoped access.
 - Support allow and deny rules over:
  folders/groups,
  specific entries,
  entry fields where needed,
  and operation types.
 - Keep specific deny rules higher priority than broad allow rules.
 - Model “not yet decided” separately from “denied”.
 Exit criteria:
 - A policy evaluator exists for token, resource, and operation tuples.
 - Explicit deny overrides allow.
 - Unspecified access is distinguishable from denied access.
 - Tests cover allow, deny, inherited group scope, and exact-entry scope behavior.
 - `go test ./...` passes.
 ### API Segment E: gRPC Authentication And Authorization Enforcement
 Scope:
 - Replace the current single static bearer-token interceptor with token-backed auth.
 - Authenticate callers using issued KeePassGO API tokens.
 - Authorize every gRPC method against token policy.
 - Apply scope checks to lifecycle, list, read, mutation, copy, and password-generation RPCs.
 Exit criteria:
 - gRPC requests authenticate through stored API tokens rather than one static shared secret.
 - Every RPC enforces token-specific authorization before mutating or revealing vault data.
 - Unauthorized requests return the correct authz/authn gRPC status.
 - Integration tests cover permitted, denied, expired, and revoked token behavior.
 - `go test ./...` passes.
 ### API Segment F: Approval Queue And Pending Access Requests
 Scope:
 - When a token requests access to a resource that is neither explicitly allowed nor denied:
  create a pending approval request.
 - Include:
  token identity,
  client name,
  requested operation,
  requested group/entry scope,
  requested time,
  and permanence choice.
 - Allow the request to be accepted, denied, or canceled by the user.
 Exit criteria:
 - Unspecified access creates a pending approval instead of silently denying or allowing.
 - Pending approvals are queryable from the application layer.
 - Canceling the prompt results in the API request failing without granting access.
 - Tests cover pending creation, approval, denial, and cancellation.
 - `go test ./...` passes.
 ### API Segment G: Approval UI
 Scope:
 - Show a user-facing approval screen/dialog when a pending API request needs a decision.
 - Provide actions:
  allow once,
  deny once,
  allow permanently,
  deny permanently,
  cancel.
 - Make the requested scope and operation clear to the user.
 - Ensure the dialog appears only for requests not already decided.
 Exit criteria:
 - A pending request triggers a visible approval surface in the app.
 - The user can allow, deny, or cancel from the UI.
 - Permanent decisions become persisted policy rules.
 - UI tests cover each approval outcome.
 - `go test ./...` passes.
 ### API Segment H: gRPC Request Blocking And Resume Behavior
 Scope:
 - Define how an in-flight gRPC call waits for or fails on user approval.
 - Hold the request while approval is pending within a bounded timeout.
 - Return unauthenticated or permission-denied when denied/canceled/expired.
 - Resume the original call automatically when approval is granted.
 Exit criteria:
 - Pending requests block safely without leaking goroutines.
 - Allowed requests resume and complete without the client reissuing the call where practical.
 - Denied and canceled requests return a consistent gRPC status code and message.
 - Tests cover timeout, allow, deny, and cancel paths.
 - `go test ./...` passes.
 ### API Segment I: Token Management UI
 Scope:
 - Add UI for listing API tokens.
 - Create token flow with one-time secret display.
 - Edit token display metadata and expiration.
 - Disable, revoke, and rotate tokens.
 - Show effective policy summary per token.
 Exit criteria:
 - Users can manage API tokens from the app UI end to end.
 - One-time token display is explicit and not re-shown later.
 - Expiration and disable state are visible.
 - UI tests cover create, rotate, disable, revoke, and edit flows.
 - `go test ./...` passes.
 ### API Segment J: Policy Management UI
 Scope:
 - Let users define folder, entry, and operation scopes for each token.
 - Show explicit allow and deny rules.
 - Show inherited implications of a folder-level rule.
 - Let users review prior permanent decisions created from approval prompts.
 Exit criteria:
 - Users can inspect and edit token policy from the UI.
 - Folder-level and entry-level rules are distinguishable and editable.
 - Permanent prompt decisions are visible as policy.
 - UI tests cover rule creation, update, and deletion.
 - `go test ./...` passes.
 ### API Segment K: Audit And Event History
 Scope:
 - Record token issuance, rotation, revoke, approval, deny, and prompt outcomes.
 - Record authorization failures and expirations without logging secret material.
 - Provide a bounded event history visible in the UI and/or gRPC admin surface.
 Exit criteria:
 - Security-relevant API token events are captured without secret leakage.
 - Approval outcomes and policy changes are auditable.
 - Tests cover audit generation for the main token lifecycle and approval actions.
 - `go test ./...` passes.
 ### Segment 1: Application State Ownership
 Scope: