Security whitepaper
Enterprise controls for supervised agent execution.
buildr-plannr is designed as a control plane for humans delegating software work to agents. The security model keeps authentication, workspace authorization, agent policy, approval gates, and verification evidence explicit before work is accepted.
Architecture and environment separation
buildr-plannr is a Next.js App Router application deployed through AWS-managed environments with public marketing routes and authenticated workspace routes separated at the route, session, and deployment layers.
- Public routes expose marketing, pricing, security, legal, and support material only.
- Application routes under `/app` require a validated session before workspace data is rendered.
- Development, staging, and production use separate AWS accounts, Terraform state, Cognito settings, Stripe configuration, and deployment secrets.
- The secure dev site posture requires shared preview or development sites to stay protected before any non-public workspace data is entered.
Evidence references
- src/lib/routes.ts
- docs/security/dev-site-notes.md
- docs/engineering/deployment.md
- docs/adr/0002-nextjs-16-aws-hosting.md
Cognito authentication and access control
Authentication is built around Cognito-backed custom login flows, application sessions, and workspace role checks instead of relying on a generic hosted login surface.
- Cognito user pools provide password policy, token revocation, account recovery, and optional MFA controls.
- Application sessions are created only after token validation and are scoped to the authenticated user.
- Workspace roles distinguish owners, admins, planners, reviewers, viewers, and agent actors.
- Enterprise SSO setup is documented with callback URLs, logout URLs, claim mapping, test accounts, and rollback steps.
Evidence references
- src/lib/auth.ts
- src/lib/cognito.ts
- src/lib/cognito-jwt.ts
- docs/product/enterprise-sso-admin-guide.md
Tenant isolation and authorization
Workspace data access is modeled around explicit workspace membership, plan entitlement, and resource ownership checks before project, issue, export, billing, or agent actions can proceed.
- Repository access patterns keep workspace identifiers attached to projects, milestones, issues, comments, approvals, evidence, and import/export jobs.
- Plan entitlements gate workspace counts, project counts, issue volume, agent runs, integrations, API access, exports, retention, and audit visibility.
- Billing, admin, and support operations require separate permission decisions from ordinary planner actions.
- Support workflows avoid broad impersonation and require logged, purpose-bound intervention paths.
Evidence references
- src/lib/planner-repository.ts
- src/lib/plans.ts
- src/lib/billing-access.ts
- src/lib/customer-support.ts
Agent sandboxing, policy, and approvals
Agents are treated as attributable, high-impact actors with explicit task contracts, scoped tools, approval rules, and verification requirements before work can be accepted.
- Agent task contracts capture goal, scope, non-goals, constraints, expected output, verification commands, and rollback notes.
- Agent policies define scoped permissions, allowed tools, blocked actions, policy enforcement, approval controls, escalation routes, and emergency stop behavior.
- Sensitive actions such as exports, billing changes, integration writes, production mutations, and credential access require human approval gates.
- Context packs give agents only the project, issue, dependency, and environment context needed for the assigned work.
Evidence references
- src/lib/agent-work.ts
- src/lib/agent-workflows.ts
- src/lib/agent-policy-guide.ts
- docs/product/agent-task-contract-schema.md
Encryption, secrets, backups, and retention
Data protection relies on AWS-managed encryption where practical, secret values outside source control and Terraform state, plan-based retention, and restore procedures that require evidence before customer claims are made.
- DynamoDB, S3, Cognito, Stripe references, and logs are documented as separate data stores with distinct backup and recovery behavior.
- Application secrets are stored in managed secret stores and are never committed or printed in diagnostics.
- Customer exports, import artifacts, audit records, and workspace data retention are governed by plan entitlements and legal hold overrides.
- Restore procedures require owner approval, temporary-table validation, conditional writes, and post-restore evidence.
Evidence references
- docs/security/backup-restore-retention.md
- docs/security/secrets.md
- src/lib/retention-policy.ts
- src/lib/import-export.ts
Audit logs and verification evidence
The product is designed to preserve who did what, which agent or human initiated it, what policy allowed it, and which verification evidence closed the work.
- Audit events cover authentication, role changes, billing, exports, imports, agent runs, approval requests, and support actions.
- Verification evidence can include tests, logs, screenshots, PR links, coverage deltas, deployment run IDs, and residual risks.
- Admin diagnostics expose redacted operational state without leaking secrets or private context.
- Enterprise plans reserve longer audit retention, export APIs, and security review evidence.
Evidence references
- src/lib/audit-log.ts
- src/lib/observability.ts
- src/lib/admin-diagnostics.ts
- docs/security/observability.md
CI gates and AWS deployment model
Production readiness depends on repeatable CI, Terraform validation, OIDC-based deployment roles, environment-scoped secrets, and deployment evidence captured before release signoff.
- CI runs lint, typecheck, unit coverage, Playwright, build, dependency audit, secret scan, and Terraform validation gates.
- Terraform modules model Cognito, CloudFront/WAF, S3, DynamoDB, secrets, route records, and deployment roles.
- AWS account bootstrap follows the BuildrLab DevOps pattern with dev/prod accounts, OIDC roles, remote bootstrap evidence, and readiness registry records.
- Production deploys require plan/apply evidence, smoke tests, rollback notes, and owner signoff.
Evidence references
- .github/workflows/ci.yml
- .github/workflows/deploy.yml
- infra
- docs/engineering/ops-readiness-evidence.md
Operational readiness and incident response
Operational controls define how BuildrLab monitors, triages, communicates, and recovers from incidents that affect planner availability, security, billing, authentication, or agent execution.
- Incident response defines severity levels, roles, customer communication, evidence capture, and postmortem expectations.
- On-call runbooks cover application, API, AWS, Cognito, Stripe, database, queue, and background-job surfaces.
- SOC 2 readiness maps current controls to security, availability, and confidentiality criteria while tracking unresolved launch blockers.
- Enterprise review artifacts are linked from security and sales surfaces for procurement readiness.
Evidence references
- docs/engineering/incident-response-playbook.md
- docs/engineering/on-call-runbook.md
- docs/security/soc2-readiness-gap-analysis.md
- docs/security/enterprise-controls.md