# Implementation Plan: Credential Filtering API & Parsed Output

**Branch**: `003-credential-filtering-api` | **Date**: 2026-01-21 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/003-credential-filtering-api/spec.md`

## Summary

Enhance the LastID Rust SDK with comprehensive credential filtering helpers (issuer DID, subject DID, domain constraints, claim-level filters), typed credential response parsing with convenience accessors, and type-specific parsed credential structs. The goal is to provide an extremely flexible, fluent API for presentation requests while eliminating complex JSON parsing for customers accessing verified claims.

## Technical Context

**Language/Version**: Rust 1.89+ (2024 edition)
**Primary Dependencies**: serde, serde_json, chrono, thiserror, async-trait
**Storage**: N/A (SDK is stateless; configuration from TOML/env vars)
**Testing**: cargo test, cargo llvm-cov (95%+ coverage per constitution)
**Target Platform**: All platforms (Linux, macOS, Windows, iOS, Android, WASM)
**Project Type**: Single library crate with feature flags
**Performance Goals**: Zero-cost abstractions; no runtime overhead for unused constraints
**Constraints**: Must maintain backward compatibility; all new code must pass `clippy::pedantic`
**Scale/Scope**: 33 functional requirements, 8 new examples, ~15 new types/structs

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Notes |
|-----------|--------|-------|
| I. Customer-Facing Quality | ✅ PASS | All new public APIs will have rustdoc with examples (FR-031, FR-032, FR-033) |
| II. Test Coverage | ✅ PASS | 95%+ coverage via cargo llvm-cov; property-based tests for parsers |
| III. Code Cleanliness | ✅ PASS | `clippy::pedantic`, `#![forbid(unsafe_code)]`, cargo fmt |
| IV. Cross-Platform Compatibility | ✅ PASS | No platform-specific code needed; uses existing abstractions |
| V. Safe Updates | ✅ PASS | Additive changes only; existing APIs unchanged; Edit over Write |
| VI. Maintainability | ✅ PASS | Functions <50 lines; modules <500 lines; type-state pattern |
| VII. Security-First | ✅ PASS | No secrets handled; input validation at API boundaries (FR-008) |

**Gate Status**: ✅ PASSED - No violations identified.

## Project Structure

### Documentation (this feature)

```text
specs/003-credential-filtering-api/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
│   ├── constraints.md   # Constraint type definitions
│   └── parsed-types.md  # Parsed credential struct definitions
└── tasks.md             # Phase 2 output (/speckit.tasks)
```

### Source Code (repository root)

```text
src/
├── policies/
│   ├── mod.rs                    # Module re-exports (existing)
│   ├── base.rs                   # BaseCredentialPolicy (existing)
│   ├── traits.rs                 # PolicyBuilder trait (existing)
│   ├── constraints.rs            # NEW: CredentialConstraint types
│   ├── persona.rs                # PersonaPolicy + .with_email_domain() (modify)
│   ├── verified_email.rs         # + .with_domain_constraint() (modify)
│   ├── employment.rs             # + .with_employer_did() (modify)
│   ├── trust.rs                  # + .with_minimum_level() (modify)
│   ├── age_proof.rs              # + .with_minimum_age() (modify)
│   └── verified_persona.rs       # + .with_email_domain() (modify)
├── types/
│   ├── mod.rs                    # Module re-exports (modify)
│   ├── verified_credential.rs    # + typed accessors (modify)
│   ├── verified_response.rs      # NEW: Multi-credential response
│   ├── device_attestation.rs     # NEW: DeviceAttestation struct
│   ├── device_security.rs        # NEW: DeviceSecurity struct
│   ├── field_verification.rs     # NEW: FieldVerificationMetadata
│   └── parsed/                   # NEW: Typed credential structs
│       ├── mod.rs
│       ├── persona.rs            # ParsedPersona
│       ├── employment.rs         # ParsedEmployment
│       ├── verified_email.rs     # ParsedVerifiedEmail
│       ├── verified_phone.rs     # ParsedVerifiedPhone
│       ├── verified_persona.rs   # ParsedVerifiedPersona
│       └── age_proof.rs          # ParsedAgeProof
└── lib.rs                        # Update crate-level docs (modify)

examples/
├── enterprise_domain_filter.rs   # NEW: FR-026
├── subject_binding.rs            # NEW: FR-027
├── typed_response_parsing.rs     # NEW: FR-028
├── multi_credential_chain.rs     # NEW: FR-029
├── employment_verification.rs    # UPDATE: FR-030
├── persona_credential.rs         # UPDATE: FR-030
└── verified_email_credential.rs  # UPDATE: FR-030

tests/
├── unit/
│   ├── constraints_test.rs       # NEW: Constraint validation tests
│   └── parsed_credentials_test.rs # NEW: Parsed struct tests
└── integration/
    └── filtering_test.rs         # NEW: End-to-end filtering tests
```

**Structure Decision**: Single library crate with modular source organization. New types go in `src/types/parsed/` subdirectory. Constraints go in `src/policies/constraints.rs`. This follows existing SDK patterns.

## Complexity Tracking

> No constitution violations identified. This section is empty.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| N/A | N/A | N/A |

---

## Post-Design Constitution Re-Check

*Verified after Phase 1 design completion (2026-01-21)*

| Principle | Status | Post-Design Verification |
|-----------|--------|--------------------------|
| I. Customer-Facing Quality | ✅ PASS | All contracts specify rustdoc with examples; FR-031, FR-032, FR-033 mandate documentation |
| II. Test Coverage | ✅ PASS | data-model.md includes validation rules; tests planned in `tests/unit/` and `tests/integration/` |
| III. Code Cleanliness | ✅ PASS | All structs derive standard traits; type-state pattern maintained per research.md |
| IV. Cross-Platform Compatibility | ✅ PASS | No platform-specific code in design; uses serde/serde_json (cross-platform) |
| V. Safe Updates | ✅ PASS | Design adds methods to existing structs; no breaking changes to public API |
| VI. Maintainability | ✅ PASS | New modules under 500 lines; parsed/ subdirectory keeps types organized |
| VII. Security-First | ✅ PASS | Input validation at build-time (FR-008); no secrets/PII handling |

**Post-Design Gate Status**: ✅ PASSED

---

## Generated Artifacts

| Artifact | Path | Description |
|----------|------|-------------|
| Research | `specs/003-credential-filtering-api/research.md` | IDP constraint mapping, type-state patterns, device attestation fields |
| Data Model | `specs/003-credential-filtering-api/data-model.md` | Entity definitions, validation rules, state transitions |
| Constraints API | `specs/003-credential-filtering-api/contracts/constraints.md` | Policy builder constraint method contracts |
| Parsed Types API | `specs/003-credential-filtering-api/contracts/parsed-types.md` | VerifiedCredential accessors, VerifiedResponse, parsed structs |
| Quickstart | `specs/003-credential-filtering-api/quickstart.md` | Usage examples for all new capabilities |

---

## Next Steps

Run `/speckit.tasks` to generate the implementation task list (`tasks.md`).
