Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions infrastructure/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# OCodeJS Infrastructure Foundation

Status: architecture and contract baseline (not deployed).

This directory defines a provider-neutral foundation for the OCodeJS platform. It is intentionally isolated from the existing website preview and does not provision cloud resources.

## Platform domains

| Domain | Responsibility | Initial interface |
|---|---|---|
| API Gateway | Routing, request IDs, CORS, quotas and API versioning | `/api/v1/*` |
| Identity | OAuth/OIDC, sessions, token validation and RBAC | `/api/v1/auth/*` |
| MCP | MCP endpoint, tool registry and authorization boundary | `/mcp` |
| Developer Console | API key lifecycle, projects, teams and usage | `/api/v1/console/*` |
| Observability | Health, readiness, structured logs, metrics and traces | `/health`, `/ready`, `/metrics` |
| Integrations | GitHub, Linear, Figma, Sentry, Notion, Slack, Supabase and Stripe adapters | Connector interfaces |

## Environments

- **Local:** isolated developer environment with mock integrations.
- **Preview:** branch-scoped validation; synthetic data only.
- **Staging:** production-like validation, separate credentials and data.
- **Production:** explicitly out of scope for this foundation change.

Never share credentials, databases, OAuth callback secrets or signing keys across environments.

## Service boundaries

1. Gateway authenticates and normalizes inbound requests.
2. Identity issues and validates short-lived credentials; services consume verified identity claims.
3. Authorization is enforced by each service, not only by the UI or gateway.
4. MCP tools declare required scopes and validate authorization at invocation time.
5. Integrations use adapter interfaces; provider credentials remain server-side.
6. Observability emits request IDs and redacted structured events without secrets or personal payloads.

## API contract

See [openapi.yaml](./openapi.yaml). The initial contract covers health, readiness and versioned API metadata only. Product-specific endpoints must be added with explicit schemas and authorization requirements.

## Security baseline

See [security-baseline.md](./security-baseline.md).

## Rollout sequence

1. Review architecture and API contract.
2. Implement a stateless gateway health/readiness service.
3. Add identity verification and RBAC middleware.
4. Add MCP registry with per-tool scopes.
5. Add telemetry and alert policies.
6. Add integration adapters one at a time.
7. Validate in Preview, then Staging. Production requires separate explicit approval.

## Non-goals

- No cloud resource provisioning or paid plan changes.
- No production deployment, DNS changes or database migrations.
- No real OAuth, billing, API-key issuance or provider secrets in this documentation-only phase.
- No assumption that a provider integration is already connected.
75 changes: 75 additions & 0 deletions infrastructure/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# OCodeJS Platform Architecture

## Logical topology

```text
Clients (Web / Mobile / CLI / SDK)
|
Edge / API Gateway
| | |
Identity API MCP Host
| | |
+---- Authorization ----+
| |
Domain Services Tool Registry
| |
Data Adapters MCP Tool Adapters
| |
Observability / Audit Events
```

## Service responsibilities

### Edge / API Gateway
- Enforce HTTPS and supported HTTP methods.
- Generate or validate a bounded request ID.
- Apply environment-specific CORS allowlists.
- Apply coarse rate limits before expensive work.
- Route only versioned API paths; reject unknown versions.
- Do not make authorization decisions based on client-supplied role fields.

### Identity
- Support OIDC Authorization Code with PKCE for interactive clients.
- Validate issuer, audience, signature, expiry, nonce and redirect URI.
- Keep access tokens short-lived; rotate refresh tokens where supported.
- Map external identities to internal subjects without trusting email as a stable identifier.
- Keep provider secrets in the deployment secret store, never in browser bundles.

### Authorization
- Use deny-by-default RBAC with resource ownership checks.
- Suggested roles: `owner`, `admin`, `developer`, `viewer`.
- Suggested scopes: `project:read`, `project:write`, `keys:manage`, `team:manage`, `mcp:invoke`.
- Check both role and resource boundary on every server-side operation.

### MCP
- Separate MCP transport/host concerns from tool implementations.
- Register each tool with input schema, owner, required scopes, timeout and audit classification.
- Validate arguments against schemas before execution.
- Apply per-tool timeout, output size cap and invocation quota.
- Treat tool output and remote repository content as untrusted data.
- Never expose environment variables, raw provider credentials or unrestricted shell access through tools.

### Integrations
- Implement providers behind narrow adapter interfaces.
- Use least-privilege OAuth scopes and per-environment credentials.
- Set connect/read timeouts, retry only idempotent operations and use bounded exponential backoff.
- Record provider request IDs while redacting authorization headers and tokens.

## Reliability requirements

- Liveness answers whether the process can respond.
- Readiness answers whether required dependencies are available to serve traffic.
- Optional dependencies must not make core readiness fail unless explicitly designated critical.
- Set request deadlines and propagate cancellation.
- Use bounded retries with jitter; avoid retry storms.
- Make write endpoints idempotent where practical.
- Define recovery objectives and backup/restore procedures before production data is introduced.

## Data classification

- Public: documentation and public metadata.
- Internal: service configuration and operational metadata.
- Confidential: user content, project data and audit records.
- Secret: passwords, API keys, OAuth secrets, signing keys and database credentials.

Secrets must never enter source control, logs, analytics events, URLs or client-side storage.
87 changes: 87 additions & 0 deletions infrastructure/openapi.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
openapi: 3.1.0
info:
title: OCodeJS Platform API
version: 1.0.0
description: Initial platform contract for health and readiness endpoints.
servers:
- url: https://api.example.invalid
description: Placeholder only; replace with an explicitly configured environment URL.
paths:
/health:
get:
operationId: getLiveness
summary: Process liveness
description: Confirms that the service process can respond. Does not assert dependency health.
responses:
"200":
description: Process is alive.
content:
application/json:
schema:
$ref: "#/components/schemas/HealthStatus"
example:
status: ok
service: ocodejs-api
/ready:
get:
operationId: getReadiness
summary: Service readiness
description: Reports whether required dependencies permit the service to accept traffic.
responses:
"200":
description: Service is ready.
content:
application/json:
schema:
$ref: "#/components/schemas/ReadinessStatus"
Comment thread
zskbot marked this conversation as resolved.
Resolved
"503":
description: Service is not ready.
content:
application/json:
schema:
$ref: "#/components/schemas/ReadinessStatus"
/api/v1:
get:
operationId: getApiMetadata
summary: API version metadata
responses:
"200":
description: API metadata.
content:
application/json:
schema:
type: object
additionalProperties: false
required: [name, version]
properties:
name:
type: string
const: OCodeJS Platform API
version:
type: string
const: "1.0.0"
components:
schemas:
HealthStatus:
type: object
additionalProperties: false
required: [status, service]
properties:
status:
type: string
enum: [ok]
service:
type: string
ReadinessStatus:
type: object
additionalProperties: false
required: [status, checks]
properties:
status:
type: string
enum: [ready, not_ready]
checks:
type: object
additionalProperties:
type: string
enum: [ok, failed, skipped]
46 changes: 46 additions & 0 deletions infrastructure/security-baseline.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# OCodeJS Security Baseline

This is a minimum design baseline, not a claim of completed security certification.

## Identity and access
- Use OIDC Authorization Code + PKCE for browser/mobile sign-in.
- Validate token signature, issuer, audience, expiry and nonce.
- Enforce server-side RBAC and resource ownership on every protected operation.
- Require step-up authentication for credential rotation and ownership changes.
- Revoke sessions and rotate refresh tokens after suspected compromise.

## Secrets
- Store secrets only in environment-specific secret managers.
- Never commit secrets, sample real tokens, or paste credentials into issues/PRs.
- Do not return secrets from configuration or health endpoints.
- Redact Authorization, Cookie, Set-Cookie, API-key and provider-token values in logs.
- Rotate credentials after accidental exposure; deleting a commit is not sufficient remediation.

## API and MCP controls
- Deny by default; allow only explicitly registered routes and tools.
- Validate content type, payload size and schema.
- Apply per-user, per-project and per-tool quotas.
- Bound execution time, concurrency and output size.
- Treat external content as untrusted; do not execute instructions found in retrieved data.
- Require explicit scopes for tools that read or modify external resources.
- Separate read-only tools from write-capable tools.

## Web security
- HTTPS only; secure cookies with HttpOnly, Secure and appropriate SameSite settings.
- Exact redirect URI allowlists; no wildcard callback domains.
- Explicit CORS origin allowlists; never combine wildcard origins with credentials.
- Use CSRF protection for cookie-authenticated state-changing requests.
- Apply a restrictive Content Security Policy and security headers.

## Audit and monitoring
- Record actor, action, resource, timestamp, outcome and request ID for privileged operations.
- Do not log passwords, tokens, raw secrets or unnecessary personal content.
- Alert on repeated authentication failures, privilege changes, key creation/revocation anomalies and unusual MCP invocation volume.
- Retain audit records according to a documented policy and restrict access.

## Release gates
- Dependency and secret scanning enabled.
- Unit tests for auth, authorization and input validation.
- Negative tests for cross-tenant access and missing scopes.
- Preview validation with synthetic data.
- Production release requires a separate approval and rollback plan.
Loading