# Kestrel Banking — Product Requirements (v4.2)

Kestrel Banking is a private-banking vault. Clients sign in with a Secure ID, see their accounts and cards with net liquidity, move money between their deposit accounts behind an explicit authorization step, and open new products through a three-step application with a calendar date picker.

**Problem.** Clients must be certain that every transfer or product funding is authorized deliberately and that the money is always accounted for: balances and net liquidity must reconcile after every operation.

## Users
- **Private-banking client** — See total liquidity at a glance, move funds safely and open new products without paperwork.
- **Applicant** — Complete identity, residence and funding steps with clear field-level feedback.

## Goals
- No money is created or lost: every debit lands somewhere and net liquidity reconciles.
- Nothing moves until the client explicitly authorizes it.
- Every field error is specific and appears before an application advances.

## Vault sign-in (AUT)

Secure ID login, session gating and sign-out.

- **FR-AUT-01** (Must) A valid Secure ID and Access Code open the Portfolio; the header shows the client’s handle, the Portfolio and Move Funds navigation and Sign Out.
  - URL /kestrel/dashboard, heading "Portfolio", "Welcome back, @<secure ID>"
- **FR-AUT-02** (Must) Unrecognised credentials are refused with one generic message and the login card stays.
  - "Access denied — secure ID or access code not recognised"
- **FR-AUT-03** (Should) "Enter Vault Access" is disabled until both fields contain input; spaces alone do not count as a Secure ID.
- **FR-AUT-04** (Could) Show / Hide toggles whether the Access Code is displayed in clear text; the button label alternates between "Show" and "Hide".
- **FR-AUT-05** (Must) Every vault page requires a session: signed-out visits go to /kestrel/login, and after Sign Out the Back button does not reveal portfolio data.

## Portfolio (PRT)

Facilities, net liquidity and sidebar.

- **FR-PRT-01** (Must) Accounts & Cards lists every facility with its type, mask and balance (cards show "Balance owed"); Net Liquidity equals the sum of deposit balances minus card balances owed.
  - Checking •••• 2841 $12,480.55; Savings •••• 5530 $48,210.00; Vela Signature •••• 7710 "Balance owed $642.12"
  - Net Liquidity $60,048.43 (12,480.55 + 48,210.00 − 642.12)
- **FR-PRT-02** (Could) The sidebar offers three products and two vault alerts.
  - Savings "4.10% APY · no lockup", Checking "Zero-fee daily liquidity", Platinum Credit Card "3× points · concierge"
  - Alerts "Statement for September is ready." and "New device sign-in verified."

## Move funds (TRF)

Internal transfers with a Review Protocol and authorization dialog.

- **FR-TRF-01** (Must) A transfer is reviewed first and only moves money when the client clicks "Authorize Transfer" in the "Authorization Protocol" dialog, which restates origin, recipient and amount.
  - Checking → Savings $500.00 shows Origin Checking •••• 2841, Recipient Savings •••• 5530, Amount $500.00
  - After authorizing: Checking $11,980.55, Savings $48,710.00, Net Liquidity unchanged at $60,048.43
  - Savings → Checking $10,000 gives Checking $22,480.55, Savings $38,210.00
- **FR-TRF-02** (Should) Only deposit accounts are transfer facilities: Origin and Recipient list Checking •••• 2841 and Savings •••• 5530, never the card. The form shows the origin’s "Available" balance, which follows the selected origin.
  - Origin Checking: "Available: $12,480.55"; Origin Savings: "Available: $48,210.00"
- **FR-TRF-03** (Must) Origin and recipient must differ.
  - "Origin and recipient facilities must differ"; no dialog
- **FR-TRF-04** (Must) The amount must be a number above zero.
  - Empty, "0" or "ten": "Enter a liquid capital amount above $0.00"
- **FR-TRF-05** (Must) A transfer may use the full available balance but not a cent more.
  - 12480.56 from Checking: "Insufficient liquidity in origin facility"
  - 12480.55 succeeds: Checking $0.00, Savings $60,690.55
- **FR-TRF-06** (Should) Abort or Escape closes the authorization dialog without moving money and the form keeps its values.
  - After Abort the form still shows $250 and Checking stays $12,480.55
- **FR-TRF-07** (Could) Editing the amount hides the previous validation error.

## Product application (APP)

Three-step application: identity, residence, initial allocation.

- **FR-APP-01** (Must) The application has three steps — Identity Verification, Residence Information, Initial Asset Allocation — and a successful application provisions a new facility with a confirmation.
  - Heading "Apply for Savings"; date hint "March 22, 1985"
  - Externally funded $100: "Facility Approved" — "Savings was successfully provisioned." and "Savings •••• 1148 · Opening balance $100.00"
  - Dashboard shows four facilities and Net Liquidity $60,148.43
- **FR-APP-02** (Should) A facility funded from an existing account is debited that account by the funding amount and opens with the same balance; net liquidity is unchanged.
  - Checking funded $1,000 from Checking •••• 2841: new "Checking •••• 1148 · Opening balance $1,000.00"; source $11,480.55; Net Liquidity $60,048.43
- **FR-APP-03** (Should) An internal funding source must cover the amount.
  - $20,000 from Checking: "Insufficient liquidity in origin facility" under the amount
- **FR-APP-04** (Should) Funding source and amount are both required.
  - "Select a funding source" and "Funding amount required"
- **FR-APP-05** (Must) Funding a new credit card from an account keeps the money accounted for: the amount funded becomes the card’s balance so Net Liquidity is unchanged.
  - Platinum Credit Card funded $100 from Checking: Checking $12,380.55 and Net Liquidity $60,048.43
- **FR-APP-06** (Should) Identity Continue is disabled until first name, last name and a valid date of birth are present; the hint reads "Format: YYYY-MM-DD" until a valid date is typed, then the long date.
  - "1985-03-22" enables Continue with hint "March 22, 1985"
- **FR-APP-07** (Should) Date of birth must be a real calendar date from 1900-01-01 up to today, typed as YYYY-MM-DD.
  - "2023-02-29", "03/22/1985", "1899-12-31" and any future date disable Continue
  - "2024-02-29" is accepted: "February 29, 2024"
- **FR-APP-08** (Should) The calendar popup ("Open calendar") fills the field in ISO format and can navigate by month and year.
  - Popup "Choose date of birth" opens on January 1990
  - July 1972, day 4: field "1972-07-04", hint "July 4, 1972"; reopening shows July 1972 with day 4 selected; "Previous month" twice reaches May 1972
- **FR-APP-09** (Should) Residence fields are required and each shows its own error.
  - "Primary residence required", "City required", "State required", "Valid 5-digit ZIP code required"
  - ZIP "9410" keeps the ZIP error
- **FR-APP-10** (Must) A ZIP code is exactly five digits and is treated as text: leading zeros are valid and anything else is refused.
  - 02101 (Massachusetts) is accepted and "Initial Asset Allocation" opens
  - "1e4" shows "Valid 5-digit ZIP code required"
- **FR-APP-11** (Could) Back keeps every value typed in earlier steps.
  - Residence "456 Oak Ave", "Springfield", California, 94105; Identity Jane / Smith / 1985-03-22
- **FR-APP-12** (Could) An unknown product URL shows "Unknown product" with a "Back to Portfolio" button.
  - /kestrel/apply/Gold%20Bullion: "We couldn't find “Gold Bullion”."

## Vault API (API)

REST access to facilities, transfers and applications.

- **FR-API-01** (Should) Facilities are served only with a bearer token; amounts are in cents.
  - No token: 401
  - With token: 200, three facilities, netLiquidity 6004843
- **FR-API-02** (Should) Transfer endpoints enforce the same rules as the form.
  - Review with a card as recipient: 422 "Select origin and recipient facilities"
  - Valid $50 transfer: 201, id "KTX-…", status "authorized", Checking balance 1243055
- **FR-API-03** (Could) Applications reject unknown products and report every field error.
  - Unknown product: 404 "Unknown product Gold"
  - Empty sections: 422 with errors for firstName, lastName, dob, address, city, state, zip, source and amount

## Non-functional requirements

- **NFR-01** (Must) Security: vault pages and API facilities are never available without authentication, and a generic message is shown for bad credentials.
- **NFR-02** (Should) Accessibility: dialogs close with Escape.
- **NFR-03** (Should) Data format: money is displayed as $ with thousands separators and two decimals; dates are entered and stored as YYYY-MM-DD.

## Glossary and rules

- **Net Liquidity** — Deposit balances minus the balance owed on cards.
- **Facility** — Any account or card in the portfolio.
- **Review Protocol** — The review step before the Authorization Protocol dialog.

## Out of scope

- External wires (simulated as new funds)
- Statement and alert content