adam/procurement-ingest
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/procurement-ingest.git synced 2026-09-30 20:03:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
procurement-ingest/infra/deploy-role/README.md
Adam Moussa f67d8b9907
Some checks are pending
Deploy / deploy (push) Waiting to run
Details
feat(api): procurement-api read stack + OpenAPI docs (SHOC reconciliation path) (#127) 
* feat(api): add procurement-api stack - read API + OpenAPI docs page

Third CDK stack: API Gateway REST API (IAM SigV4) over both pipelines'
tables, replacing SHOC's retired SyncController cross-account DynamoDB
scan as the reconciliation/backfill path.

- lambdas/api/: handler (healthcheck + docs-token gate + router dispatch),
  router (single route table), pagination (opaque cursor, hostile -> 400),
  Decimal-safe serialization, wo_repo/po_repo reads. No VendorReplies.
- OpenAPI 3.1 spec as source of truth incl. top-level webhooks section
  documenting the outbound SHOC feed; phase-2 write endpoints x-planned
  (router answers 501). Self-contained /docs page, no CDN.
- Auth: AWS_IAM on data routes + resource policy scoped to exactly
  arn:aws:iam::396287094661:role/shoc-backend-dev on GET/*; /docs and
  /openapi.json carve-out is token-gated in the Lambda via shared
  web_ui_auth (fail-closed, INFRA-74 posture).
- KMS: explicit Decrypt/DescribeKey on the DynamoDB CMK from SSM
  (name-imported table drops the key association - INFRA-104 class).
- Alarms: errors/throttles/duration(p99>=22.5s) + gateway 5xx, ALARM-only
  to site-alerts. No access logging in v1 (docs ?token= shim stays out of
  logs); cloud_watch_role=False.
- Tests: handler auth-seam + routing + Decimal round-trip; moto cursor
  pagination incl. hostile cursors; spec<->router drift gate; bundle
  AST pins for the api command; pytest.ini --cov + loader siblings.
- Deploy role: third stack DescribeStacks ARN + procurement-api smoke
  invoke ARN (re-run create-deploy-role.sh before merge).

* harden(api): apply sh-security-review findings to procurement-api

Fan-out (6 detectors) + review findings resolved:

Correctness / DoS:
- pagination: require EXACT key-set match (was subset) so a partial/foreign
  composite cursor can't reach DynamoDB as an inconsistent ExclusiveStartKey
  -> ValidationException -> 500; comments Query now pins the cursor's
  work_order_id to the path entity.
- handler: map botocore ValidationException to 400 (defense in depth) so a
  crafted cursor can't drive the zero-threshold 5xx alarm.
- web_ui_auth: compare tokens as bytes; a non-ASCII presented token now fails
  closed (401) instead of crashing hmac.compare_digest into a 500. Resolves the
  pre-existing xfail(strict) follow-up test; hardens the web UIs too.

Docs page:
- typeStr() now escapes the one spec-derived string that reached innerHTML.
- spec inlined into the docs <script> block escapes "<" -> < (</script>
  breakout guard); /openapi.json still served byte-faithful.
- Cache-Control: no-store + Referrer-Policy: no-referrer on docs responses so
  the ?token= URL stays out of caches/Referer.
- spec-drift test asserts the committed spec carries no "</" / "<!--".

IAM / IaC:
- resource policy enumerates the 7 data GET resources instead of GET/* so a
  future GET route can't silently inherit SHOC cross-account reach.
- kms:Decrypt grant gains a kms:ViaService=dynamodb condition.
- stage throttling (50 rps / 100 burst) bounds the unauthenticated /docs blast
  radius below the 10k account default.
- corrected the PATCH/POST comment (same-account callers aren't blocked by the
  resource policy; 501 handler + absent write grant are the gate).
- documented the RETAIN log-group first-deploy rollback trap and the
  resource-policy-needs-redeploy gotcha in-stack.

Mandatory GPT-4.1 cross-family review of the full policy surface: no BLOCK/FIX.
675 tests pass, ruff clean, cdk synth green.
2026-07-23 19:32:20 -04:00

2.2 KiB
Raw Blame History

Deploy role: githubdeploy-procurement-ingest (seahaven-prod)

OIDC deploy role for this repo's GitHub Actions pipeline in AWS account 011934824531 (seahaven-prod), us-east-1. Created as part of the migration from the management account (328440206208); the mgmt role of the same name stays untouched until decommission as the emergency mgmt deploy path.

Files

File Purpose
trust-policy.json OIDC trust: repo:Sea-Haven-Industries/procurement-ingest:ref:refs/heads/main only
permissions-policy.json sts:AssumeRole on the four cdk-hnb659fds-* bootstrap roles, cloudformation:DescribeStacks scoped to this repo's stacks + CDKToolkit (cd-cdk health check), and lambda:InvokeFunction on exactly the three smoke-gated function ARNs (post-deploy smoke gate)
create-deploy-role.sh Idempotent create-or-update from the two JSON files, profile seahaven-prod

Maintenance note: DescribeStacks is scoped to stack/po-ingest/*, stack/WorkorderIngestStack/*, stack/procurement-api/* (added with the procurement-api stack), and stack/CDKToolkit/*. If another stack is ever added to this CDK app, add its ARN pattern here and re-run the review-then-apply flow — otherwise the cd-cdk health check on the new stack will AccessDenied.

Why the SmokeInvokeLambda statement exists

deploy.yaml runs scripts/post-deploy-smoke.sh under the deploy role's own session, not the assumed cdk-* roles. Without lambda:InvokeFunction on the smoke-gated function ARNs (the two email processors + procurement-api) the smoke gate hits AccessDenied and every deploy fails closed. The mgmt-era grant was applied out-of-band and undocumented; keeping it in these reviewed artifacts closes that gap. Scope it to exactly the named ARNs, never Resource: "*".

Change process

  1. Edit the JSON artifacts on a branch; both gates must pass on the exact files before anything is applied: GPT-4.1 cross-family review (cross_review.py) and /sh-security-review.
  2. Run ./create-deploy-role.sh (idempotent) with the seahaven-prod profile.
  3. Verify: aws iam simulate-principal-policy for the bootstrap-role AssumeRole and both InvokeFunction ARNs, then a real pipeline run.