README
¶
Runnable Examples
Self-contained examples demonstrating Pericarp's authentication and authorization systems.
Authentication (authn/)
Walks through the full authentication lifecycle:
- RSA key generation and JWT service setup
- OAuth flow initiation with PKCE
- Code exchange and state validation
- Agent + Credential + Account creation via
FindOrCreateAgent - Session creation, validation, and revocation
- JWT issuance and validation
- Identity context propagation (
ContextWithAgent/AgentFromCtx) - Resource ownership and tenant isolation (
ResourceOwnershipFromCtx/VerifyAccountAccess)
go run ./examples/authn/
go test -v -race ./examples/authn/
Authorization (authz/)
Demonstrates authorization decisions using both the PolicyDecisionPoint (pure Go) and CasbinAuthorizationChecker:
- Role-based access control (viewer / editor / admin)
- ODRL prohibition overrides (deny beats allow)
- Account-scoped roles
- Default deny for agents with no permissions
- Behavioral parity between PDP and Casbin implementations
- Identity context and resource ownership integration
go run ./examples/authz/
go test -v -race ./examples/authz/
Projection (projection/)
Sketches the recommended Postgres + DynamoDB layering: Postgres is the authoritative event store (global ordered feed + crash-safe subscriptions), and a background subscriber projects events into a DynamoDB read model. Crash recovery happens from Postgres — the subscriber resumes from its checkpoint and re-applies events.
- Single atomic write path (Postgres); no cross-database dual write
- Subscriber wired with
GormCheckpointStore,GormParkingLot, andPostgresListener(LISTEN/NOTIFY wake, polling fallback) - At-least-once DynamoDB projection made correct by an idempotent conditional write keyed on the global feed position (replays are no-ops; application stays monotonic)
- Why the handler does not use
TxFromContext: a DynamoDB write cannot join the subscriber's Postgres batch transaction
# needs live Postgres + DynamoDB
POSTGRES_DSN=postgres://... DYNAMO_PROJECTION_TABLE=accounts \
AWS_REGION=us-east-1 go run ./examples/projection/
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main demonstrates the Pericarp authentication lifecycle.
|
Package main demonstrates the Pericarp authentication lifecycle. |
|
Package main demonstrates the Pericarp authorization system.
|
Package main demonstrates the Pericarp authorization system. |
|
Package main sketches the recommended way to combine Postgres and DynamoDB: Postgres is the authoritative event store (it provides the global ordered feed and crash-safe subscriptions), and DynamoDB holds a read model built by a background subscriber.
|
Package main sketches the recommended way to combine Postgres and DynamoDB: Postgres is the authoritative event store (it provides the global ordered feed and crash-safe subscriptions), and DynamoDB holds a read model built by a background subscriber. |
Click to show internal directories.
Click to hide internal directories.