mirror of
https://github.com/norandom/OpenUltraSAST.git
synced 2026-10-20 21:49:28 +00:00
chore: add kiro spec-driven tooling and steering docs
Add the Kiro-style agentic SDLC tooling used to drive this project: the .opencode/skills/kiro-* skill set (discovery, spec init/requirements/design/ tasks, validation, implementation, review, steering), the .kiro/settings templates, and AGENTS.md describing the workflow. Update the spec docs (assessment/design/requirements/tasks) to current state. Scope tests/test_opencode_skills.py to the project's own openultrasast-* skills so the third-party kiro-* tooling (which uses a different frontmatter convention) no longer breaks the frontmatter check. Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Marius Ciepluch
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
8fe8911020
commit
6699f1f8f9
@@ -0,0 +1,69 @@
|
||||
# API Standards
|
||||
|
||||
[Purpose: consistent API patterns for naming, structure, auth, versioning, and errors]
|
||||
|
||||
## Philosophy
|
||||
- Prefer predictable, resource-oriented design
|
||||
- Be explicit in contracts; minimize breaking changes
|
||||
- Secure by default (auth first, least privilege)
|
||||
|
||||
## Endpoint Pattern
|
||||
```
|
||||
/{version}/{resource}[/{id}][/{sub-resource}]
|
||||
```
|
||||
Examples:
|
||||
- `/api/v1/users`
|
||||
- `/api/v1/users/:id`
|
||||
- `/api/v1/users/:id/posts`
|
||||
|
||||
HTTP verbs:
|
||||
- GET (read, safe, idempotent)
|
||||
- POST (create)
|
||||
- PUT/PATCH (update)
|
||||
- DELETE (remove, idempotent)
|
||||
|
||||
## Request/Response
|
||||
|
||||
Request (typical):
|
||||
```json
|
||||
{ "data": { ... }, "metadata": { "requestId": "..." } }
|
||||
```
|
||||
|
||||
Success:
|
||||
```json
|
||||
{ "data": { ... }, "meta": { "timestamp": "...", "version": "..." } }
|
||||
```
|
||||
|
||||
Error:
|
||||
```json
|
||||
{ "error": { "code": "ERROR_CODE", "message": "...", "field": "optional" } }
|
||||
```
|
||||
(See error-handling for rules.)
|
||||
|
||||
## Status Codes (pattern)
|
||||
- 2xx: Success (200 read, 201 create, 204 delete)
|
||||
- 4xx: Client issues (400 validation, 401/403 auth, 404 missing)
|
||||
- 5xx: Server issues (500 generic, 503 unavailable)
|
||||
Choose the status that best reflects the outcome.
|
||||
|
||||
## Authentication
|
||||
- Credentials in standard location
|
||||
```
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
- Reject unauthenticated before business logic
|
||||
|
||||
## Versioning
|
||||
- Version via URL/header/media-type
|
||||
- Breaking change → new version
|
||||
- Non-breaking → same version
|
||||
- Provide deprecation window and comms
|
||||
|
||||
## Pagination/Filtering (if applicable)
|
||||
- Pagination: `page`, `pageSize` or cursor-based
|
||||
- Filtering: explicit query params
|
||||
- Sorting: `sort=field:asc|desc`
|
||||
Return pagination metadata in `meta`.
|
||||
|
||||
---
|
||||
_Focus on patterns and decisions, not endpoint catalogs._
|
||||
@@ -0,0 +1,67 @@
|
||||
# Authentication & Authorization Standards
|
||||
|
||||
[Purpose: unify auth model, token/session lifecycle, permission checks, and security]
|
||||
|
||||
## Philosophy
|
||||
- Clear separation: authentication (who) vs authorization (what)
|
||||
- Secure by default: least privilege, fail closed, short-lived tokens
|
||||
- UX-aware: friction where risk is high, smooth otherwise
|
||||
|
||||
## Authentication
|
||||
|
||||
### Method (choose + rationale)
|
||||
- Options: JWT, Session, OAuth2, hybrid
|
||||
- Choice: [our method] because [reason]
|
||||
|
||||
### Flow (high-level)
|
||||
```
|
||||
1) User proves identity (credentials or provider)
|
||||
2) Server verifies and issues token/session
|
||||
3) Client sends token per request
|
||||
4) Server verifies token and proceeds
|
||||
```
|
||||
|
||||
### Token/Session Lifecycle
|
||||
- Storage: httpOnly cookie or Authorization header
|
||||
- Expiration: short-lived access, longer refresh (if used)
|
||||
- Refresh: rotate tokens; respect revocation
|
||||
- Revocation: blacklist/rotate on logout/compromise
|
||||
|
||||
### Security Pattern
|
||||
- Enforce TLS; never expose tokens to JS when avoidable
|
||||
- Bind token to audience/issuer; include minimal claims
|
||||
- Consider device binding and IP/risk checks for sensitive actions
|
||||
|
||||
## Authorization
|
||||
|
||||
### Permission Model
|
||||
- Choose one: RBAC / ABAC / ownership-based / hybrid
|
||||
- Define roles/attributes centrally; avoid hardcoding across codebase
|
||||
|
||||
### Checks (where to enforce)
|
||||
- Route/middleware: coarse-grained gate
|
||||
- Domain/service: fine-grained decisions
|
||||
- UI: conditional rendering (no security reliance)
|
||||
|
||||
Example pattern:
|
||||
```typescript
|
||||
requirePermission('resource:action'); // route
|
||||
if (!user.can('resource:action')) throw ForbiddenError(); // domain
|
||||
```
|
||||
|
||||
### Ownership
|
||||
- Pattern: owner OR privileged role can act
|
||||
- Verify on entity boundary before mutation
|
||||
|
||||
## Passwords & MFA
|
||||
- Passwords: strong policy, hashed (bcrypt/argon2), never plaintext
|
||||
- Reset: time-limited token, single-use, notify user
|
||||
- MFA: step-up for risky operations (policy-driven)
|
||||
|
||||
## API-to-API Auth
|
||||
- Use API keys or OAuth client credentials
|
||||
- Scope keys minimally; rotate and audit usage
|
||||
- Rate limit by identity (user/key)
|
||||
|
||||
---
|
||||
_Focus on patterns and decisions. No library-specific code._
|
||||
@@ -0,0 +1,46 @@
|
||||
# Database Standards
|
||||
|
||||
[Purpose: guide schema design, queries, migrations, and integrity]
|
||||
|
||||
## Philosophy
|
||||
- Model the domain first; optimize after correctness
|
||||
- Prefer explicit constraints; let database enforce invariants
|
||||
- Query only what you need; measure before optimizing
|
||||
|
||||
## Naming & Types
|
||||
- Tables: `snake_case`, plural (`users`, `order_items`)
|
||||
- Columns: `snake_case` (`created_at`, `user_id`)
|
||||
- FKs: `{table}_id` referencing `{table}.id`
|
||||
- Types: timezone-aware timestamps; strong IDs; precise money types
|
||||
|
||||
## Relationships
|
||||
- 1:N: FK in child
|
||||
- N:N: join table with compound key
|
||||
- 1:1: FK + UNIQUE
|
||||
|
||||
## Migrations
|
||||
- Immutable migrations; always add rollback
|
||||
- Small, focused steps; test on non-prod first
|
||||
- Naming: `{seq}_{action}_{object}` (e.g., `002_add_email_index`)
|
||||
|
||||
## Query Patterns
|
||||
- ORM for simple CRUD and safety; raw SQL for complex/perf-critical
|
||||
- Avoid N+1 (eager load/batching); paginate large sets
|
||||
- Index FKs and frequently filtered/sorted columns
|
||||
|
||||
## Connection & Transactions
|
||||
- Use pooling (size/timeouts based on workload)
|
||||
- One connection per unit of work; close/return promptly
|
||||
- Wrap multi-step changes in transactions
|
||||
|
||||
## Data Integrity
|
||||
- Use NOT NULL/UNIQUE/CHECK/FK constraints
|
||||
- Validate at DB when appropriate (defense in depth)
|
||||
- Prefer generated columns for consistent derivations
|
||||
|
||||
## Backup & Recovery
|
||||
- Regular backups with retention; test restores
|
||||
- Document RPO/RTO targets; monitor backup jobs
|
||||
|
||||
---
|
||||
_Focus on patterns and decisions. No environment-specific settings._
|
||||
@@ -0,0 +1,54 @@
|
||||
# Deployment Standards
|
||||
|
||||
[Purpose: safe, repeatable releases with clear environment and pipeline patterns]
|
||||
|
||||
## Philosophy
|
||||
- Automate; test before deploy; verify after deploy
|
||||
- Prefer incremental rollout with fast rollback
|
||||
- Production changes must be observable and reversible
|
||||
|
||||
## Environments
|
||||
- Dev: fast iteration; debugging enabled
|
||||
- Staging: mirrors prod; release validation
|
||||
- Prod: hardened; monitored; least privilege
|
||||
|
||||
## CI/CD Flow
|
||||
```
|
||||
Code → Test → Build → Scan → Deploy (staged) → Verify
|
||||
```
|
||||
Principles:
|
||||
- Fail fast on tests/scans; block deploy
|
||||
- Artifact builds are reproducible (lockfiles, pinned versions)
|
||||
- Manual approval for prod; auditable trail
|
||||
|
||||
## Deployment Strategies
|
||||
- Rolling: gradual instance replacement
|
||||
- Blue-Green: switch traffic between two pools
|
||||
- Canary: small % users first, expand on health
|
||||
Choose per risk profile; document default.
|
||||
|
||||
## Zero-Downtime & Migrations
|
||||
- Health checks gate traffic; graceful shutdown
|
||||
- Backwards-compatible DB changes during rollout
|
||||
- Separate migration step; test rollback paths
|
||||
|
||||
## Rollback
|
||||
- Keep previous version ready; automate revert
|
||||
- Rollback faster than fix-forward; document triggers
|
||||
|
||||
## Configuration & Secrets
|
||||
- 12-factor config via env; never commit secrets
|
||||
- Secret manager; rotate; least privilege; audit access
|
||||
- Validate required env vars at startup
|
||||
|
||||
## Health & Monitoring
|
||||
- Endpoints: `/health`, `/health/live`, `/health/ready`
|
||||
- Monitor latency, error rate, throughput, saturation
|
||||
- Alerts on SLO breaches/spikes; tune to avoid fatigue
|
||||
|
||||
## Incident Response & DR
|
||||
- Standard playbook: detect → assess → mitigate → communicate → resolve → post-mortem
|
||||
- Backups with retention; test restore; defined RPO/RTO
|
||||
|
||||
---
|
||||
_Focus on rollout patterns and safeguards. No provider-specific steps._
|
||||
@@ -0,0 +1,59 @@
|
||||
# Error Handling Standards
|
||||
|
||||
[Purpose: unify how errors are classified, shaped, propagated, logged, and monitored]
|
||||
|
||||
## Philosophy
|
||||
- Fail fast where possible; degrade gracefully at system boundaries
|
||||
- Consistent error shape across the stack (human + machine readable)
|
||||
- Handle known errors close to source; surface unknowns to a global handler
|
||||
|
||||
## Classification (decide handling by source)
|
||||
- Client: Input/validation/user action issues → 4xx
|
||||
- Server: System failures/unexpected exceptions → 5xx
|
||||
- Business: Rule/state violations → 4xx (e.g., 409)
|
||||
- External: 3rd-party/network failures → map to 5xx or 4xx with context
|
||||
|
||||
## Error Shape (single canonical format)
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human-readable message",
|
||||
"requestId": "trace-id",
|
||||
"timestamp": "ISO-8601"
|
||||
}
|
||||
}
|
||||
```
|
||||
Principles: stable code enums, no secrets, include trace info.
|
||||
|
||||
## Propagation (where to convert)
|
||||
- API layer: Convert domain errors → HTTP status + canonical body
|
||||
- Service layer: Throw typed business errors, avoid stringly-typed errors
|
||||
- Data/external layer: Wrap provider errors with safe, actionable codes
|
||||
- Unknown errors: Bubble to global handler → 500 + generic message
|
||||
|
||||
Example pattern:
|
||||
```typescript
|
||||
try { return await useCase(); }
|
||||
catch (e) {
|
||||
if (e instanceof BusinessError) return respondMapped(e);
|
||||
logError(e); return respondInternal();
|
||||
}
|
||||
```
|
||||
|
||||
## Logging (context over noise)
|
||||
Log: operation, userId (if available), code, message, stack, requestId, minimal context.
|
||||
Do not log: passwords, tokens, secrets, full PII, full bodies with sensitive data.
|
||||
Levels: ERROR (failures), WARN (recoverable/edge), INFO (key events), DEBUG (diagnostics).
|
||||
|
||||
## Retry (only when safe)
|
||||
Retry when: network/timeouts/transient 5xx AND operation is idempotent.
|
||||
Do not retry: 4xx, business errors, non-idempotent flows.
|
||||
Strategy: exponential backoff + jitter, capped attempts; require idempotency keys.
|
||||
|
||||
## Monitoring & Health
|
||||
Track: error rates by code/category, latency, saturation; alert on spikes/SLI breaches.
|
||||
Expose health: `/health` (live), `/health/ready` (ready). Link errors to traces.
|
||||
|
||||
---
|
||||
_Focus on patterns and decisions. No implementation details or exhaustive lists._
|
||||
@@ -0,0 +1,55 @@
|
||||
# Security Standards
|
||||
|
||||
[Purpose: define security posture with patterns for validation, authz, secrets, and data]
|
||||
|
||||
## Philosophy
|
||||
- Defense in depth; least privilege; secure by default; fail closed
|
||||
- Validate at boundaries; sanitize for context; never trust input
|
||||
- Separate authentication (who) and authorization (what)
|
||||
|
||||
## Input & Output
|
||||
- Validate at API boundaries and UI forms; enforce types and constraints
|
||||
- Sanitize/escape based on destination (HTML, SQL, shell, logs)
|
||||
- Prefer allow-lists over block-lists; reject early with minimal detail
|
||||
|
||||
## Authentication & Authorization
|
||||
- Authentication: verify identity; issue short-lived tokens/sessions
|
||||
- Authorization: check permissions before actions; deny by default
|
||||
- Centralize policies; avoid duplicating checks across code
|
||||
|
||||
Pattern:
|
||||
```typescript
|
||||
if (!user.hasPermission('resource:action')) throw ForbiddenError();
|
||||
```
|
||||
|
||||
## Secrets & Configuration
|
||||
- Never commit secrets; store in secret manager or env
|
||||
- Rotate regularly; audit access; scope minimal
|
||||
- Validate required env vars at startup; fail fast on missing
|
||||
|
||||
## Sensitive Data
|
||||
- Minimize collection; mask/redact in logs; encrypt at rest and in transit
|
||||
- Restrict access by role/need-to-know; track access to sensitive records
|
||||
|
||||
## Session/Token Security
|
||||
- httpOnly + secure cookies where possible; TLS everywhere
|
||||
- Short expiration; rotate on refresh; revoke on logout/compromise
|
||||
- Bind tokens to audience/issuer; include minimal claims
|
||||
|
||||
## Logging (security-aware)
|
||||
- Log auth attempts, permission denials, and sensitive operations
|
||||
- Never log passwords, tokens, secrets, full PII; avoid full bodies
|
||||
- Include requestId and context to correlate events
|
||||
|
||||
## Headers & Transport
|
||||
- Enforce TLS; HSTS
|
||||
- Set security headers (CSP, X-Frame-Options, X-Content-Type-Options)
|
||||
- Prefer modern crypto; disable weak protocols/ciphers
|
||||
|
||||
## Vulnerability Posture
|
||||
- Prefer secure libraries; keep dependencies updated
|
||||
- Static/dynamic scans in CI; track and remediate
|
||||
- Educate team on common classes; encode as patterns above
|
||||
|
||||
---
|
||||
_Focus on patterns and principles. Link concrete configs to ops docs._
|
||||
@@ -0,0 +1,47 @@
|
||||
# Testing Standards
|
||||
|
||||
[Purpose: guide what to test, where tests live, and how to structure them]
|
||||
|
||||
## Philosophy
|
||||
- Test behavior, not implementation
|
||||
- Prefer fast, reliable tests; minimize brittle mocks
|
||||
- Cover critical paths deeply; breadth over 100% pursuit
|
||||
|
||||
## Organization
|
||||
Options:
|
||||
- Co-located: `component.tsx` + `component.test.tsx`
|
||||
- Separate: `/src/...` and `/tests/...`
|
||||
Pick one as default; allow exceptions with rationale.
|
||||
|
||||
Naming:
|
||||
- Files: `*.test.*` or `*.spec.*`
|
||||
- Suites: what is under test; Cases: expected behavior
|
||||
|
||||
## Test Types
|
||||
- Unit: single unit, mocked dependencies, very fast
|
||||
- Integration: multiple units together, mock externals only
|
||||
- E2E: full flows, minimal mocks, only for critical journeys
|
||||
|
||||
## Structure (AAA)
|
||||
```typescript
|
||||
it('does X when Y', () => {
|
||||
// Arrange
|
||||
const input = setup();
|
||||
// Act
|
||||
const result = act(input);
|
||||
// Assert
|
||||
expect(result).toEqual(expected);
|
||||
});
|
||||
```
|
||||
|
||||
## Mocking & Data
|
||||
- Mock externals (API/DB); never mock the system under test
|
||||
- Use factories/fixtures; reset state between tests
|
||||
- Keep test data minimal and intention-revealing
|
||||
|
||||
## Coverage
|
||||
- Target: [% overall]; higher for critical domains
|
||||
- Enforce thresholds in CI; exceptions require review rationale
|
||||
|
||||
---
|
||||
_Focus on patterns and decisions. Tool-specific config lives elsewhere._
|
||||
Reference in New Issue
Block a user