From 89f715e985a4fce774751f67f82e26d860acc8f4 Mon Sep 17 00:00:00 2001 From: zskbot <241179063+zskbot@users.noreply.github.com> Date: Wed, 11 Nov 2026 05:31:03 +0700 Subject: [PATCH 1/4] docs(infra): add OCodeJS infrastructure foundation --- infrastructure/README.md | 59 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 infrastructure/README.md diff --git a/infrastructure/README.md b/infrastructure/README.md new file mode 100644 index 0000000..98af194 --- /dev/null +++ b/infrastructure/README.md @@ -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. From 1dca3a26418aa7565afd2239b272da53baf60d58 Mon Sep 17 00:00:00 2001 From: zskbot <241179063+zskbot@users.noreply.github.com> Date: Wed, 11 Nov 2026 05:31:05 +0700 Subject: [PATCH 2/4] docs(infra): define OCodeJS service boundaries --- infrastructure/architecture.md | 75 ++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 infrastructure/architecture.md diff --git a/infrastructure/architecture.md b/infrastructure/architecture.md new file mode 100644 index 0000000..b187b36 --- /dev/null +++ b/infrastructure/architecture.md @@ -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. From cd8b890d0db190c96d4673142503330f4ba2ec8b Mon Sep 17 00:00:00 2001 From: zskbot <241179063+zskbot@users.noreply.github.com> Date: Wed, 11 Nov 2026 05:31:08 +0700 Subject: [PATCH 3/4] docs(api): add initial OCodeJS health API contract --- infrastructure/openapi.yaml | 87 +++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 infrastructure/openapi.yaml diff --git a/infrastructure/openapi.yaml b/infrastructure/openapi.yaml new file mode 100644 index 0000000..9a7ade6 --- /dev/null +++ b/infrastructure/openapi.yaml @@ -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" + "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] From 457b6ca7fe0ab2e2a525aa7de14e445df7ba35b0 Mon Sep 17 00:00:00 2001 From: zskbot <241179063+zskbot@users.noreply.github.com> Date: Wed, 11 Nov 2026 05:31:11 +0700 Subject: [PATCH 4/4] docs(security): define OCodeJS platform security baseline --- infrastructure/security-baseline.md | 46 +++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 infrastructure/security-baseline.md diff --git a/infrastructure/security-baseline.md b/infrastructure/security-baseline.md new file mode 100644 index 0000000..706abd5 --- /dev/null +++ b/infrastructure/security-baseline.md @@ -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.