Palladin .NET Backend

Palladin is a zero-knowledge password manager for AI agents. This repository contains the .NET 10 backend: a modular monolith that coordinates identities, encrypted vault data, agents, grants, notifications, search, and audit records without receiving plaintext credentials or client-held encryption keys.

The backend is pre-production. Its current migration baseline intentionally assumes empty databases and may be incompatible with earlier development data.

Palladin ecosystem

Project overview and public repositories · Mobile client · Website

Each component owns its setup and contribution guide. This repository can be used independently of the private project workspace.

Security model

Security is an architectural constraint, not an optional feature:

• Vault secrets cross the API only as authenticated encrypted envelopes. The backend must never receive or log plaintext credentials.
• Master keys, vault keys, private keys, and decrypted values belong on clients and must never be added to server DTOs, persistence models, telemetry, or logs.
• The service is zero-knowledge for vault contents, not zero-data. Account, organization, agent, authorization, delivery-state, and audit metadata remain visible to the backend and must be protected accordingly.
• Every FastEndpoints endpoint explicitly declares an authorization policy or AllowAnonymous().
• Mutations load tracked aggregates through a module DomainWriteContext, invoke domain behavior, and commit through the domain context so invariants and events cannot be bypassed.
• Runtime secrets must come from environment-specific configuration or a secret manager. The committed development and testing credentials are local-only fixtures and must never be deployed.
• Forwarded headers are ignored unless trusted proxies or networks are explicitly configured. Production deployments must terminate TLS and configure that trust boundary deliberately.

The canonical vault wire contract and cryptographic boundaries are documented in Vault protocol 2. Start an architecture review at docs/architecture/README.md.

Every running build exposes its corresponding source revision and license through the anonymous GET /api/health response. Official container images also carry OCI source, revision, and license labels.

Do not report suspected vulnerabilities in a public issue. Use GitHub private vulnerability reporting from the repository's Security tab, or contact the maintainers privately through the Palladin organization.

Architecture

The application is one deployable API with isolated bounded contexts:

Area	Responsibility
src/Palladin.Api	Process entry point, HTTP pipeline, health checks, and module composition
src/core	Shared security, persistence, messaging, API, analytics, and infrastructure building blocks
Identity	Accounts, authentication, organizations, membership, recovery, and key-directory metadata
Vault	Encrypted vaults and entries, grants, delivery envelopes, synchronization, and key rotation
Agents	Agent enrollment, API keys, proof-of-possession authentication, and lifecycle
Audit	Append-only audit records and asynchronous export
Notification	Inbox, SignalR, email, and push orchestration
Search	Event-fed, access-scoped read models
PublicAssetCatalog	Safely acquired and published public icons and presentation assets

Modules communicate asynchronously through MassTransit contracts. Read and write persistence are split per module, and cross-module read concerns use event-fed OpenHost modules instead of live database queries.

Key technologies include FastEndpoints, Entity Framework Core with PostgreSQL, MassTransit with RabbitMQ, Hangfire, SignalR, NodaTime, Serilog, xUnit, Shouldly, NSubstitute, and Testcontainers.

Local development

Prerequisites:

• .NET 10 SDK
• Docker Engine with Docker Compose

Start PostgreSQL, RabbitMQ, and the local S3-compatible storage used by presentation assets:

docker compose up -d --wait

The compose stack binds every service to loopback only and initializes isolated development and test databases. The committed development configuration points storage-dependent features at the LocalStack S3 endpoint on http://localhost:4566; the API creates the required public-asset bucket when it starts.

Restore, build, and run the API:

dotnet restore Palladin.sln
dotnet build Palladin.sln --no-restore
dotnet run --project src/Palladin.Api/Palladin.Api.csproj

The development API listens on http://localhost:5000. Check GET /api/health; Scalar API documentation is available at /scalar only in Development.

For local overrides, copy the tracked placeholder template to the ignored local settings file and fill in your own Google Web client ID:

cp src/Palladin.Api/appsettings.Local.example.json \
  src/Palladin.Api/appsettings.Local.json

Alternatively, use ASP.NET's double-underscore environment syntax. Environment variables take precedence over the local settings file:

Modules__Identity__Google__ClientId=your-local-client-id \
dotnet run --project src/Palladin.Api/Palladin.Api.csproj

The Google client ID is public client configuration rather than a secret, but Palladin's value stays outside tracked defaults so a public clone or fork cannot silently use Palladin's OAuth project. Never commit appsettings.Local.json, .env files, service-account JSON, signing keys, tokens, or production connection strings.

Tests

Run the same pipeline as CI:

dotnet restore Palladin.sln
dotnet build Palladin.sln --no-restore
dotnet test Palladin.sln --no-build --verbosity normal

The unit project can be run independently:

dotnet test tests/Palladin.Tests.Unit/Palladin.Tests.Unit.csproj

Integration tests require the local PostgreSQL test databases. A fresh docker compose up -d postgres initializes them; external delivery and storage boundaries are replaced with test doubles where the suite requires isolation.

The Shared Unlock fixture scanner checks document the public-vector provenance and test the narrowly scoped Gitleaks exceptions. Run bash scripts/test-gitleaks-fixtures.sh when changing those fixtures or the scanner configuration.

Contributing

Read AGENTS.md before changing code and the relevant module document before implementing a feature. Keep changes within a vertical slice, preserve zero-knowledge boundaries, add behavior-focused tests, and run the full build and test pipeline before opening a pull request.

All changes are reviewed through pull requests to main. Security boundary changes, integration-contract changes, and schema changes should be called out explicitly in the pull request description.

License and notices

Copyright 2026 Patryk Roguszewski, trading as Patryk Roguszewski IT Solutions.

The backend is licensed under the GNU Affero General Public License v3.0 only, identified as AGPL-3.0-only. See NOTICE, TRADEMARKS.md, THIRD_PARTY_NOTICES.md, and the CycloneDX SBOM for additional information.