overfolder/overslash

Purpose and entry points

Overslash is a multi-tenant gateway that lets AI agents invoke authenticated external actions without receiving credentials. It combines secrets, OAuth connections, permission inheritance, human approvals, auditing, and HTTP/MCP execution.

Primary runtime entry points:

• Unified CLI/server binary: crates/overslash-cli/src/main.rs, with serving modes in crates/overslash-cli/src/serve.rs and crates/overslash-cli/src/web.rs.

• HTTP API/router: crates/overslash-api/src/lib.rs and crates/overslash-api/src/routes/mod.rs.

• MCP client/server support: crates/overslash-mcp/src/lib.rs, crates/overslash-api/src/routes/mcp/dispatch.rs.

• SvelteKit dashboard: dashboard/src/routes/+layout.svelte, dashboard/src/routes/+page.svelte.

API boundary, tenancy, and identity

The Rust/Axum API is the central control plane. Route modules expose management APIs for organizations, identities/agents, groups, credentials, services, approvals, audit records, billing, and events. Authentication supports sessions, magic links, external/OIDC providers, and OAuth authorization-server behavior.

Tenancy and request isolation are enforced at API/database boundaries through subdomain and rate-limit middleware plus scoped repositories:

• crates/overslash-api/src/middleware/subdomain.rs

• crates/overslash-api/src/routes/auth/mod.rs

• crates/overslash-db/src/scopes/org.rs

Authorization and approval chain

Permission evaluation models user → agent → subagent chains, applies ceilings and matching rules, and resolves missing authority into approval workflows. Action requests are validated and permission-gated before execution; approvals can be read, resolved, replayed, or auto-called after approval.

Key policy/execution gates:

• crates/overslash-core/src/permissions/evaluate.rs

• crates/overslash-api/src/routes/actions/permission_gate.rs

• crates/overslash-api/src/routes/approvals/replay.rs

This is the core safety boundary: external calls should occur only after identity resolution, permission-chain evaluation, and any required approval.

Service definitions and action resolution

Service templates describe third-party APIs, their auth schemes, actions, risks, scopes, and MCP capabilities. YAML registry files are imported/validated into a normalized service model; instances then layer organization-specific configuration, credentials, and discovered tools over templates.

Relevant paths:

• services/github.yaml

• crates/overslash-core/src/openapi/compile.rs

• crates/overslash-core/src/template_validation/core/service_shape.rs

• crates/overslash-api/src/services/platform_services/reconcile.rs

Action resolution maps an agent request to an allowed service/action, resolves parameters and secrets, then selects HTTP, platform, or MCP calling paths:

• crates/overslash-api/src/routes/actions/resolve.rs

• crates/overslash-api/src/services/action_caller.rs

• crates/overslash-api/src/services/mcp_caller.rs

Credentials, OAuth, and secret handling

Secrets are encrypted and versioned; connections encapsulate OAuth or bring-your-own credentials so agents do not receive raw values. OAuth supports upstream providers, connection initiation/callback flows, incremental scopes, and MCP client authorization.

Important boundaries:

• Crypto and secret injection: crates/overslash-core/src/crypto.rs, crates/overslash-core/src/secret_injection.rs

• Connection flows: crates/overslash-api/src/routes/connections/initiate.rs, crates/overslash-api/src/routes/connections/callback.rs

• OAuth AS endpoints: crates/overslash-api/src/routes/oauth/authorize.rs, crates/overslash-api/src/routes/oauth/token.rs

Persistence, audit, and asynchronous signals

PostgreSQL is the system of record for organizations, identities, memberships, permission rules, encrypted secrets, OAuth connections, service instances, execution/approval state, and audit records. SQLx repositories present scoped access rather than allowing routes direct database access.

• Schema evolution: crates/overslash-db/migrations/001_create_orgs.up.sql, crates/overslash-db/migrations/105_events.up.sql

• Repository layer: crates/overslash-db/src/repos/mod.rs

• Auditing/events: crates/overslash-api/src/services/audit_capture.rs, crates/overslash-api/src/services/events/bus.rs

Events feed live dashboard behavior and approval notifications; webhooks are dispatched separately:

• crates/overslash-api/src/routes/events.rs

• crates/overslash-api/src/services/webhook_dispatcher.rs

Clients and deployment

The dashboard is a separate SvelteKit client consuming API endpoints, with primary operational surfaces for services, connections, secrets, approvals, agents, audit, and organization administration:

• dashboard/src/lib/api.ts

• dashboard/src/routes/services/+page.svelte

• dashboard/src/routes/approvals/+page.svelte

A TypeScript SDK exposes programmatic resources, UI controllers, web components, SSE/event handling, and webhook verification:

• sdk/src/client.ts

• sdk/src/resources/actions.ts

• sdk/src/controllers/events.ts

Production infrastructure is Terraform/OpenTofu targeting Google Cloud: Cloud Run, Cloud SQL/Postgres, Memorystore, load balancing, Secret Manager, Cloud Monitoring, and scheduled metrics export.

• infra/main.tf

• infra/modules/cloud-run/main.tf

• infra/modules/cloud-sql/main.tf