Security profiles and limits

Local octonode serve binds to 127.0.0.1 and trusts callers on that loopback boundary. Production mode requires a bearer credential for every /api route except /api/health, /api/health/live, /api/health/ready, /api/docs, and /api/openapi.json; the cloud gateway validates the user's JWT and workspace permissions before forwarding to the private server. Production host exposure and allowed browser origins must be configured explicitly with HOST and OCTONODE_CORS_ORIGINS. The CLI production profile also requires OCTONODE_AUTH_TOKEN and an explicit persistent OCTONODE_STORE_DIR; it refuses to start when either is missing. Readiness returns 503 when the canonical store is unreadable. Only GET on those five exact paths is public; wrong methods and prefix lookalikes remain default-deny. Gateway readiness checks only mode-required bindings and a servable Studio shell, never a tenant runtime. Release smoke uses separate API-bearer and browser-session fixtures; authenticated browser traces are prohibited.

Threat model

Architecture review decision (2026-07-25): the local OS user and local project code are trusted. Cloud workspace members, project code, and installed plugins are trusted within that workspace; the per-workspace Cloudflare Sandbox is the security boundary protecting the host and other workspaces. Production server mode never launches host node commands. Revisit this decision before allowing mutually untrusted users or third-party code inside one workspace.

Actors are the local developer, authenticated workspace member, workspace administrator, plugin author, and unauthenticated internet caller. Protected assets are project source and configuration, canonical store records and revisions, Git credentials, workspace secrets, run data, and host or cross-workspace resources. The browser/API boundary is untrusted input; the private server/store boundary is authenticated; child-process execution is trusted-local only; the cloud gateway/Sandbox boundary is the tenant isolation boundary.

Safe defaults bound untrusted work: API and source bodies are 4 MiB, webhook bodies are 1 MiB, cloud snapshots allow 2,000 files/25 MiB total/2 MiB per file, source-watch SSE concurrency is 32, run concurrency is 8, and the waiting run queue is bounded. Operators can lower connection and run caps with OCTONODE_SOURCE_WATCH_CONCURRENCY, OCTONODE_RUN_CONCURRENCY, and OCTONODE_RUN_QUEUE. Limit failures return 413 or 429 without writing the rejected input.

Secrets

Local variables are stored as mode-0600 plaintext dotenv files. Do not use the local profile on a shared host. Production deployments must use the workspace secret provider; dotenv files and secret values are excluded from project exports. Variable APIs return [redacted], run records redact declared and provenance-named secrets before persistence, and logs must never receive variable values. Updating an existing variable rotates it atomically without editing or stopping workflows. Values containing a newline or NUL and invalid variable names are rejected.

The coding assistant keeps OPENAI_API_KEY and OCTONODE_CHAT_SERVICE_TOKEN in backend service environments only. They are removed from node child-process environments and must never enter Studio, model messages, MCP arguments, conversation records, logs, traces, errors, exports, or backups. The service rejects browser Origin requests and authenticates its private run endpoint separately from the opaque caller token used by the project-bound MCP session. OCTONODE_CLOUD_INTERNAL_TOKEN also protects knowledge-corpus replacement and remains backend-only.

Workspace administration and scoped credentials

Supabase Auth issues user sessions; it does not decide workspace authorization. The Cloudflare API verifies every user JWT against the configured Supabase JWKS and expected issuer, then resolves the subject's current role from D1 for the requested personal, organization, or team workspace. Missing verifier configuration fails closed. Roles are workspace-local, so one subject may be an organization owner in one workspace and a viewer in another without either grant leaking across the boundary. A personal workspace has one immutable user:owner with every action.

The action catalog in @octonode/schema is shared by role policy, scoped API credentials, the gateway, OpenAPI, and Studio. API credentials store only a SHA-256 hash and prefix; the full secret is returned once. Every request rechecks revocation, expiration, workspace, optional project binding, and required action before Durable Object or Sandbox access. Credentials cannot mint more credentials. Identity-bound operations such as creating organizations or teams, connecting OAuth, and managing Supabase identities also require a user session. Member removal changes only the selected workspace membership; it never deletes the shared Supabase identity. Organization owners and the last team lead are protected from removal or demotion.

Workspace analytics are aggregated from the workspace-keyed Durable Object and contain only that tenant's project, workflow, execution, and data-table totals. Membership, invitation, API-key, and GitHub connection totals come from D1 using the same workspace key. The admin dashboard receives no account-wide Cloudflare telemetry and never logs or persists the one-time API-key secret.

Expansion action defaults

Every R10-R13 feature route must call the shared workspace policy service with one of these actions. An action absent from a role is denied. Personal owners, organization owners, and organization admins receive the complete catalog; organization overrides may change only the configurable roles.

A team carries no separate policy or billing account. Its orgId is the parent organization used for role overrides and, by dependent billing code, entitlements. Scoped agents still intersect this matrix with their explicit action scopes and exact workspace/project binding on every request.

Billing authority and downgrade policy

Stripe owns customers, products, prices, subscriptions, and active entitlements. Control D1 stores one projection account for a personal user or organization; a team always resolves its parent organization account. Database uniqueness prevents either a billable parent from changing customers silently or one Stripe customer from being attached to two parents.

Paid-plan state is never copied into Supabase user_metadata or trusted from a browser/JWT claim. The verified JWT subject selects the personal billable account at request time, organizations use their D1 identity, and Studio refreshes the projected Stripe subscription for the active workspace.

POST /hooks/stripe verifies the Stripe-Signature HMAC against the untouched request body with a five-minute timestamp tolerance. The unique event id enters stripe_webhook_events before any projection. Completed inbox payloads are cleared, duplicate ids are ignored, mismatched replays are rejected, and subscription, catalog, and entitlement snapshots accept only a newer (created, id) version. The scheduled Worker retries failed inbox rows and reconciles every attached customer against Stripe's paginated subscriptions and active-entitlements APIs using the pinned API version.

Permissions and entitlements answer different questions and are recorded together in billing_access_audit. Only cost-bearing mutations use the entitlement gate. Active and trialing subscriptions may use projected features; past_due keeps them for a 72-hour grace period, then fails closed. Missing entitlements and incomplete, paused, unpaid, or cancelled subscriptions fail closed. Project/data reads, export, billing access, and workspace deletion remain permission-only so downgrade never prevents recovery, payment repair, or deletion. STRIPE_API_KEY and STRIPE_WEBHOOK_SECRET are Worker secrets and never enter a browser, workspace Sandbox, event log, or audit row.

Chargeable operations use a caller-owned stable source event id and append an immutable row to usage_ledger; database triggers reject updates, deletes, duplicate reversals, and operations that would exceed an active hard quota. The same transaction updates the bounded account/meter/period projection and records each warning, soft, or hard budget threshold once. A scheduled reconciliation rebuilds those totals from the ledger, which remains authoritative even when telemetry or Stripe is unavailable.

Stripe meter deliveries use a deterministic, content-free identifier and idempotency key. Explicit ledger reversals cancel the corresponding Stripe meter event. Retryable delivery failures use capped backoff and stop after eight attempts; permanent failures stop immediately for operator review. Structured usage and budget events contain only the billable-account id, meter, quantity, threshold, and delivery status. Prompts, source payloads, command output, secrets, and user content never enter billing metrics or alerts.

Collaboration deployment controls

SOCIAL_ROLLOUT is the server authority: off, personal, a comma-separated allowlist such as personal,org:<id>, or all. The workspace permissions response exposes capabilities.collaboration, and the shared collaboration authorization boundary rejects disabled workspaces. Deployment defaults to personal; promote one test organization before all.

The GitHub App should request repository metadata/contents and pull-request read/write access only; it does not request organization administration or Actions permissions. GitHub installation access is linked only to a validated registered Architecture. The link records bounded Project IDs and repository-relative roots so webhook file paths can be routed without trusting caller-supplied roots. tokens are minted just in time inside the Cloud worker. Explicit user actions publish inline review comments or submit reviews. General workflow discussion uses a pull-request conversation comment, which supports later update/deletion; submitted review summaries are not used as mutable storage.

Before broad enablement, review cross-workspace denial, two-browser socket revocation, webhook signature/replay fixtures, stale-head suggestions, backup/restore/deletion, DLQ depth, oldest outbox age, oldest backup age, and GitHub App permissions. Abort rollout on authorization leakage, lost acknowledged writes, an unrecoverable restore, or sustained queue age beyond the operating SLO.

Slack connection security

The first Slack product slice supports public-channel history and delivery only. Its bot scopes are exactly channels:history, channels:read, chat:write, and users:read; private-channel, workspace-administration, and user-token scopes are not requested. Only a browser user with integrations:manage may install or revoke. Members with integrations:read may inspect identity, status, granted scopes, and drift, but no credential fields.

Access and refresh tokens are JSON inside a versioned AES-256-GCM envelope. The current wrapping-key version selects a base64url-encoded 32-byte key from INTEGRATION_WRAPPING_KEYS; authenticated data binds the workspace kind/id, provider, and connection id. Keep old versions during rotation until all live envelopes have been refreshed. Workspace exports and social backups omit the connection registry; operator D1 recovery snapshots contain ciphertext only. Tokens are never copied to Studio responses, queues, logs, social records, node environments, or Sandbox configuration.

/hooks/slack verifies Slack's v0 HMAC over the raw body and rejects timestamps outside five minutes before JSON parsing. The configured Slack app id and the event's team/enterprise installation mode select one connection exactly. Unbound channels retain only the unique event id, body hash, and content-free control metadata. An administrator must explicitly bind one public channel and direction before its bounded message text enters the seven-day retry inbox. Successful processing clears that inbox payload immediately; expired failed payloads are deleted by scheduled maintenance.

Provider message/thread ids and the durable Slack outbox live with chat in the workspace Durable Object, so they follow collaboration export, restore, retention, and deletion. External Slack authors carry a stable slack:<id> attribution, display label, and origin=slack; no membership row is created. Outbound messages carry an octonode_bridge metadata marker, and bot-user checks plus unique delivery/mapping/outbox keys stop echoes and retries from becoming local loops. Retry-After controls rate-limit retries, with a maximum of eight provider attempts.

Disabling a binding or beginning connection revocation stops new ingress and egress before the provider call completes. Local deletion calls chat.delete only for messages posted by the Octonode bot; Slack does not permit the bot to delete another author's message. Revocation, workspace deletion, or a local tombstone therefore must not be reported as erasing pre-existing Slack history remotely.