Resolves code scanning alerts #4 and #5 (actions/missing-workflow-permissions). Both callable workflows only need contents: read; the dependency-review callable already declares it internally, this caps the caller token to match.
* feat: add cash-position tile from boa_balance snapshots to App Home
Read the latest previous-day boa_balance snapshot (authoritative)
to display current ledger and available balance on the App Home
summary bar. Optionally surfaces today's intraday snapshot as
provisional. Walks backward up to 14 days to handle weekend/holiday
gaps, using targeted GetItem by computed key instead of a scan.
Refs: #77
* fix: null-guard cash-position tile, add error logging, drop UTC date skew and serial GetItems
- Null-guard current_ledger on the authoritative cash-position tile so a
missing ledger renders 'Not available' instead of the false '/bin/bash.00'
- Log GetCommand failures with console.error + logSafe instead of silent
catch, matching the rest of the codebase
- Derive dates from local midnight instead of toISOString UTC, so the
current-day lookup doesn't miss from 8pm ET to midnight
- Fetch all 14 balance keys in parallel with Promise.allSettled instead of
14 serial GetCommands; start previous-day walk at i=1 since today's
previous-day snapshot can't exist until tomorrow
- Use Item.as_of_date directly instead of a synthetic _asOfDate field
- Remove _asOfDate from test fixtures; add test for the null-ledger guard
---------
Co-authored-by: amoussa1229 <166072409+amoussa1229@users.noreply.github.com>
* feat(apphome): surface returned payments as a needs-action queue
Bank-returned payments carry status "Cleared" (the CSV ladder has no
Returned rung), so the status skip-list hid them from every App Home
bucket; five Feb-Apr returns ($5,256.62) surfaced only via a manual
statement reconciliation. Route on clear_status ahead of the status
skip-list: non-canceled Returned records render in an always-visible
action queue (oldest return first) plus a summary tile, and are
excluded from Outstanding totals. Terminal voided-and-bounced records
stay out of both (audit trail only). Membership keys off clear_status,
not returned_date, so redeposited checks drop back out of the queue.
Refs: #70
* docs(apphome): restore returned-queue README bullet dropped in rebase
Same-day settlement visibility plus maximal data capture from the
reporting feed. The handler gains an allowlisted endpoint parameter
(EventBridge passes {"endpoint":"current-day"} on a new 16/19/22 UTC
weekday rule; the 9am previous-day sweep is unchanged and remains
authoritative). Every response's exact bytes archive to a new
Retain-protected bucket before classification, so the feed is
replayable and auditable even across parser changes. Summary rows
become per-date boa_balance# snapshots (latest-wins on run_at, no
TTL) instead of being discarded. The staleness sweep is gated to
previous-day runs so intraday runs don't re-alert the backlog three
times a day. History events carry a via:<endpoint> audit tag outside
the replay-idempotence identity. Fixtures are sanitized real API
captures; classification histograms assert against live-verified
counts.
Refs: #66, #69
The deployed v2 pipeline was fully inert: the classifier never read
detailText (where the live API carries the ACH DES:PAYMENTS text) and
the handler keyed event dates off valueDate, which the API does not
send (it sends asOfDate) — so ACH could not classify and no event of
any kind could apply. Both proven against real captured responses.
- classifyTransaction: detailText first in the description chain;
Summary-row guard (new "summary" event); all-zeros customerReference
normalizes to empty instead of fabricating check number 0.
- BAI_CODE_EVENTS: empirical enumeration lands — 255 + 252 are both
check-numbered return credits, 266 is the no-number return credit
(text disambiguates ach_return vs electronic_return via new
fallbackEvent semantics), 455 is ach_debit via DES text or ignored
third-party autopay, 170/201/470/481 are noise.
- postingDate helper (asOfDate ?? valueDate) drives both the sort and
event dates; unmatched reason is now "missing posting date".
- Default replay window widened to trailing 7 days ending yesterday:
self-healing across missed runs; responses verified pagination-free.
Refs: #66, #69
* feat(fetchboa): v2 return/redeposit-aware reconciliation (#66)
The two-code 475/255 filter missed every return on the Jan-Jul statement
(29 ARP refer-to-maker credits, 24 electronic return credits, and the
redeposit cycles), leaving 5 paid-then-returned checks stuck at Cleared
($5,256.62, vendors unpaid). Rewrite fetchBoaTransactions around a pure
reconciliation module (src/boaRecon.js) covered by node:test:
- BAI transaction-code event map (only 475 = check paid is confirmed;
remaining codes pend the enumeration replay) with a description-text
fallback classifier for ARP refer-to-maker, return-of-posted-check
(check-numbered and electronic) and ACH DES:PAYMENTS formats. Unknown
check-shaped transactions are logged and counted, never dropped.
- Matching on check number AND amount over all candidates; wrong-amount
or collapsed-number postings fall back to a unique exact-amount match
within checks issued in the last 120 days; ambiguity means unmatched
with no write.
- Transitions always set BOTH status and clear_status (the missed
returns slipped through the divergence between them). clear_status is
bank truth: returns apply even to Cleared records, a second paid debit
on a Returned check is a redeposit back to Cleared, and a return on a
voided check is terminal voided-and-bounced. Every applied event is
appended to a history list; identical replayed events are noops.
- Optional {fromDate, toDate} replay payload (strictly validated) for
gap replays and the BAI-code enumeration runs; default stays
yesterday.
- Each run writes a boa_recon#<runDate> summary item (90-day TTL) with
per-event counts, unmatched check numbers/amounts, and unknown codes;
unmatched/unknown also console.error (Slack alerting is #71).
ACH transactions are classified but not yet acted on; bank-confirming
ACH lands with #69.
* feat(ach): bank-confirm ACH, drop CSV-date auto-clear (#69)
processPaymentCsv auto-cleared ACH the moment send_payment_on passed,
but the bank disagrees often enough to matter: settlement lags the send
date by up to 8 days, settled ACH can bounce and re-debit (Uline
$19,281.12, Heights $10,000.00 on the 5/26 overdrawn week), and voided
ACH that settled anyway returned via electronic credits invisible to a
Check-only feed. Move ACH to bank confirmation:
- processPaymentCsv: ACH rows keep their Stampli status; the send-date
auto-clear is removed. The bankConfirmed protection is unchanged, so
bank-cleared records still cannot be moved backward by the CSV.
- fetchBoaTransactions scans all payments (method filter dropped) and
processes ACH CCD lines: match by stored pmt_id first (reversals
reuse the original PMT id), then by the Stampli payment number
embedded in PMT INFO (internal spaces stripped, amount must agree),
then vendor + exact amount within send_payment_on -2..+14 days.
Settled debit -> Cleared/Cleared with dates, pmt_id persisted on the
record; credit reusing the pmt_id (or a unique same-amount return
credit against a bank-confirmed ACH) -> clear_status=Returned +
returned_date + history event. Ambiguity is unmatched, no write.
Existing DDB ACH records already Cleared by the old auto-clear are
unaffected: bank confirmation is additive and the CSV path never moves
a record backward.
Handler event contract extended (optional fromDate/toDate); cross-family
review required before merge.
* fix(fetchboa): close review findings — coverage gap, matcher corroboration, replay identity (#66)
Security-review gate (detector fan-out + verifier + GPT-4.1 cross-family)
blocked on F6 and confirmed six lower findings; all are closed here.
- F6 (HIGH): the default run now queries a trailing 3-day window
(today-3..today-1) so the Monday run covers Friday-Sunday postings the
previous-day cadence silently skipped. A per-run staleness sweep flags
never-bank-confirmed payments (ACH > 16 days, checks > 60 days) in the
summary and via console.error.
- F2: replay identity is {event, date, amount} — bankRef excluded (feeds
omit/reformat it between runs); a paid event dated on/before the
latest return in history is a replayed original, never a redeposit;
rows without a valid valueDate are routed to unmatched instead of
being applied under a substituted date; within a day, debits sort
before credits.
- F1: a check-number match with the wrong amount no longer falls
through to the amount fallback (altered-check/collapsed-posting is a
human-review case); the amount fallback requires digit-subsequence
corroboration between posting and candidate numbers; check_return
fallback requires a bank-confirmed candidate.
- F4: the ach_return amount fallback requires cleared_date within 45
days before the credit; an unattributable PMT id is an unmatched
alert, never an amount guess.
- F5: the pmt_id rung requires amount equality; mismatch is the
partial-reversal human case.
- F3: vendor prefix matching requires >= 10 normalized chars (short
names must match exactly); candidates with a conflicting stored
pmt_id are excluded; vendor+amount matches are audit-logged.
- F7: payment writes are conditioned on the snapshot's
status/clear_status and retried once against a fresh read; residual
conflicts are counted, not silently interleaved.
- F9/summary bounds: run summary pk is append-only
(boa_recon#<from>_<to>#<runAt>); unmatched list capped at 50, unknown
codes at 20 keys/16 chars, stale list at 50 (full counts kept).
- ReDoS: description bounded to 500 chars before classification;
CHECK/embedded-number regexes use bounded quantifiers.
- FBOA2-1: both BoA res.json() parses are wrapped so a malformed 200
throws a status-only error and cannot leak a body snippet.
Handler event contract extended (optional fromDate/toDate); cross-family
review required before merge.
* fix(boaRecon): add method=Check filter to matchElectronicReturn
Electronic returns only apply to checks, but the matcher was not
filtering by method, so an electronic return could incorrectly
match against a same-amount, bank-confirmed ACH record.
* fix(csv): parse M/D/YY dates with loud rejects; stop canceled rows zeroing stored fields (#65, #68)
Stampli exports switched from MM/DD/YYYY to M/D/YY, which toISODate
mangled into garbage ISO strings and slackAppHome's parseMDYLocal turned
into year-1926 dates. Canceled rows also blank 'Amount in USD' and can
blank dates, which the unconditional upsert wrote over previously stored
real values (116 records at amount_usd=0 as of the 2026-07-21
reconciliation).
- src/dates.js: shared strict parser for M/D/YY + MM/DD/YYYY (real-date
validation, 2-digit years 2000-based, plausibility window helper)
- processPaymentCsv: canonicalize send_payment_on to MM/DD/YYYY; reject
rows with unparseable/implausible dates and fail the invocation after
valid rows are processed (surfaces via errors alarm + async DLQ;
retry-safe since upserts are idempotent and existing checks are not
re-offered to BoA); only overwrite amount_usd/send_payment_on with
real values, falling back to the 'Amount' column on cancels
- BoA add_Issue/cancel_Issue now use stored record values when the CSV
row is blank (cancel_Issue previously sent amount 0.00 for voids) and
skip registration on missing date/amount instead of sending garbage;
same guard on the backfill path
- slackAppHome: use the shared parser (fixes 1926 aging)
* fix(csv): validate BoA registration data before writes; harden logging (security review)
Hardening from the /sh-security-review pass on this branch:
- BoA eligibility (resolvable amount + issue date) is now decided and
validated BEFORE the DDB upsert: a cancel-transition row we cannot act
on is rejected with the record untouched, so the transition gate stays
open for a later clean file instead of silently losing the cancel
forever (the skip guard previously ran after the status write)
- First-seen rows that are already canceled are stored but never
offered to add_Issue — registering a voided check as an active issue
created a live issue with no cancel to follow (worsened by the Amount
fallback making the previously-failing call succeed)
- isPlausibleSendYear window is now relative (year-7..year+2) instead
of hardcoded 2020-2035
- Untrusted CSV values are JSON-encoded and truncated before log
interpolation (quoted CSV cells carry newlines -> CloudWatch log-line
forgery, CWE-117)
- OAuth token-exchange failures no longer throw the raw BoA authn
response body (aligns with the PR #63 log-scrub posture)
Verified: unit smoke on the date module; full replay of the real
2026-07-21 export (1,197 rows) against live table state produces 1,197
upserts, 0 rejects, 0 spurious BoA submissions.
* fix(csv): comma-tolerant amount parsing in backfill (PR #72 review)
Number() on a hand-inserted comma-formatted string amount would NaN and
skip the check during backfill; hoist the CSV path's parseAmount to
module scope and share it. No live records are affected (all amount_usd
values are DDB Number type) — defensive consistency.
Two agentic-review findings on the payments-dashboard security surface:
- CRITICAL (CWE-862): the /slack/events endpoint (slackAppHome) performed no
Slack signing-secret verification, so an unauthenticated caller could forge
app_home_opened/block_actions events and exfiltrate payment data via
DynamoDB scans + views.publish. Add HMAC-SHA256 signature verification with
a 5-minute replay window over the raw request body, mirroring the existing
expenseReceiver pattern. Requests failing verification get a 401 before any
body parsing, DynamoDB access, or Slack API call. Adds the
SLACK_SIGNING_SECRET_NAME env var and an additive secretsmanager grant for
payments-dashboard/slack-signing-secret.
- HIGH (CWE-532): full BoA CashPro response bodies + headers were logged to
CloudWatch and persisted to DynamoDB (response_body/response_headers), which
could expose account numbers/PII. Drop those fields from both boa_txn#
records and stop logging raw bodies/headers on both the main submit path and
the backfill retry path; log status + txnId only (txnId still correlates to
BoA support for the full body).
Verification: sam validate, node --check both handlers. /sh-security-review
(detector fan-out + verifier) and GPT-4.1 cross-family review run; the
cross-family review confirmed the IAM grant is purely additive.
The two async-invoke OnFailure DLQs (payments-processPaymentCsv-async-dlq
and payments-processPayrollEmail-async-dlq) had no CloudWatch alarm, so a
failed async invocation could sit in the DLQ unnoticed. Add a
messages-present alarm for each, mirroring PayrollBatchDLQAlarm exactly:
AWS/SQS ApproximateNumberOfMessagesVisible, Maximum, threshold > 0,
Period 300, EvaluationPeriods 1, TreatMissingData notBreaching, ALARM-only
to the site-alerts SNS topic.
* Add CloudWatch alarm coverage for payments-dashboard (Wave 1)
Add 22 CloudWatch alarms to round out observability:
- Lambda Errors alarms for the 4 functions that lacked them
(slackAppHome, fetchBoaTransactions, expenseReceiver, expenseProcessor)
- Lambda Throttles alarms for all 6 functions
- Lambda Duration alarms for all 6 functions (~80% of timeout, Maximum)
- DynamoDB throttle/system-error alarms for the PaymentsDashboard table
(ReadThrottleEvents/WriteThrottleEvents/SystemErrors, TableName dim)
- API Gateway v2 alarms on the implicit ServerlessHttpApi
(5xx, 4xx, Latency p99; ApiId dim)
All alarms publish to the site-alerts SNS topic, ALARM-only, missing data
notBreaching, matching the existing payments-<fn>-errors convention from PR #48.
Documents the full alarm inventory under a new README Monitoring section.
* Drop DynamoDB SystemErrors alarm (never fires at TableName dimension)
AWS/DynamoDB SystemErrors does not emit at the TableName-only dimension,
so payments-dashboard-table-system-errors could never fire. Remove the
alarm resource and its README entry; keep Read/WriteThrottleEvents.
Add PublicAccessBlockConfiguration (BlockPublicAcls, IgnorePublicAcls,
BlockPublicPolicy, RestrictPublicBuckets all true) to PaymentsCsvBucket
and PayrollEmailBucket. Codifies the already-private runtime state
(account-level and bucket-level S3 BPA already enabled). Zero functional
change; clears checkov CKV_AWS_53/54/55/56.
The PaymentsDashboard table was migrated to SSE-KMS (alias/seahaven-dynamodb,
INFRA-95/M-3) out-of-band, but no function role had kms perms. fetchBoaTransactions
failed 6/6 daily runs with kms:Decrypt AccessDeniedException, taking the BoA
transaction feed 100% down; the other 3 table consumers were latently broken too.
- Add kms:Decrypt/GenerateDataKey/DescribeKey to processPayrollEmail,
processPaymentCsv, fetchBoaTransactions (read-write) and kms:Decrypt/DescribeKey
to slackAppHome (read-only). Actions match the lambda permissions boundary.
- Declare SSESpecification on the table to reconcile out-of-band drift (idempotent).
- Resolve the CMK arn from SSM /seahaven/dynamodb/cmk-arn.
GPT-4.1 cross-review: no blockers.
Adds seahaven-lambda-execution-boundary to Globals.Function so every
SAM-auto-generated Lambda execution role carries the boundary. Required
for the INFRA-97 github-cfn-execution-role scope-down to safely permit
iam:CreateRole on this stack.
No explicit AWS::IAM::Role resources exist in this template; the
Globals entry covers all six functions.
Refs: INFRA-103
Bring the interim CLI-created dead-letter queues, error alarms, and
SendMessage role policies for payments-processPaymentCsv and
payments-processPayrollEmail under CloudFormation control (H-8 drift).
- Add per-function async-invoke OnFailure SQS DLQs (CFN-named
payments-<fn>-async-dlq, 14d retention to match payments-payroll-batch-dlq)
- Wire EventInvokeConfig OnFailure on both functions (SAM auto-generates the
scoped sqs:SendMessage policy on each execution role); explicit retry/age
defaults locked in
- Add ALARM-only Lambda Errors alarms (Sum, threshold>0) -> site-alerts
Interim CLI resources (queues, alarms, role policies, event-invoke-configs)
removed post-deploy after the CFN-managed versions were confirmed live.
* Add dependency-review caller workflow
Add a pull_request-triggered caller that invokes the org-level
callable-dependency-review workflow to scan dependency changes and
fail on high-severity advisories.
* chore: retrigger checks
* chore: retrigger dep review (post-fix)
Audit M-22: S3 and DynamoDB traffic from the VPC was billed through
the NAT gateway; gateway endpoints are free and keep it on the AWS
backbone.
Audit L-15: payroll-batch messages were silently lost after max
receives. Adds a 14-day DLQ with maxReceiveCount 3 and an ALARM-only
notification to site-alerts so a caught failure is actually seen.
Replace the SSM Parameters section with the new Secrets Manager secret
structure (3 grouped secrets) and correct the runtime-config note.
Refs: INFRA-5, #3
The SAM layout convention requires a committed samconfig.toml.example
template; only the gitignored samconfig.toml existed. Add one with
placeholder deploy parameters (stack name, region, S3, capabilities).
Refs: #5
API tokens and credentials must live in Secrets Manager per
secrets-and-config.md, but the four original payment Lambdas still
read 10 SecureString SSM params. Move them to three grouped secrets
(slack-bot-token plaintext, boa-check-mgmt and boa-reporting as JSON),
matching the pattern the expense Lambdas already use. IAM is scoped to
secretsmanager:GetSecretValue per secret; the VPC Lambdas reach the
public endpoint over the existing NAT path. Test/reissue scripts and
the client-ssm dependency are updated/removed accordingly.
Refs: #3
* Merge expense-approval-bot into payments-dashboard
Port the Slack reaction-driven expense routing workflow (receiver +
processor) from expense-approval-bot into this stack as JavaScript ESM.
Secrets copied to payments-dashboard/ prefix in Secrets Manager.
* Fix review findings from PR #28
- Add length check before timingSafeEqual to prevent RangeError on
malformed signatures (returns 401 instead of 500)
- Check event.type === reaction_added to prevent reaction_removed
from advancing expenses
- Move getPermalink call behind isOrigin check to skip unnecessary
API call on non-origin stage transitions
* Make dashboard sections collapsible and clean up BoA audit log
- Scheduled Checks, Scheduled ACH, and Outstanding Checks sections
default to collapsed with summary line; Expand/Collapse button
toggles detail view via private_metadata state
- Filter backfill failure records from BoA submissions display
- Limit Recent BoA Submissions to 5 most recent entries
* Share Slack home publish pipeline
Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com>
