Repository navigation
Infrastructure foundation: API, MCP, identity and security contracts #56
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
89f715e
docs(infra): add OCodeJS infrastructure foundation
zskbot 1dca3a2
docs(infra): define OCodeJS service boundaries
zskbot cd8b890
docs(api): add initial OCodeJS health API contract
zskbot 457b6ca
docs(security): define OCodeJS platform security baseline
zskbot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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" | ||
| "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] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.