How veeresh-11/meika_secure works
Purpose and Entry Points
Meika Secure is a Python security/authentication platform centered on policy-driven access decisions, device trust, WebAuthn, token/grant issuance, and tamper-evident evidence. The HTTP application starts at app/main.py; API entry points include app/api/auth.py, app/api/health.py, and WebAuthn routing in app/security/webauthn/routes.py.
Request-to-Decision Enforcement Pipeline
Security processing is centralized around a pipeline/runtime boundary rather than API handlers directly deciding access. app/security/pipeline.py coordinates enforcement, app/security/runtime/engine.py supplies runtime execution, and app/security/middleware.py applies request-level integration. Decision types, precedence, failure handling, and canonicalization are defined under app/security/decision.py, app/security/precedence.py, and app/security/canonical.py; the design is explicitly fail-closed where evidence or prerequisite checks fail.
Authentication, Identity, and Session Services
API routes delegate to application services for authentication lifecycle operations: app/services/auth_service.py, app/services/session_service.py, and app/services/credential_service.py. WebAuthn is split into challenge, attestation, assertion, and mapping stages in app/security/webauthn/challenge.py, app/security/webauthn/attestation.py, and app/security/webauthn/assertion.py. Device registration and lifecycle data are represented in app/db/device_models.py and managed through app/services/device_service.py.
Policy, Risk, Device, and Graph Inputs
The authorization decision consumes independent evaluators behind the policy engine: app/security/policy/engine.py, app/security/policy/evaluator.py, and evaluator modules such as app/security/policy/evaluators/device.py and app/security/policy/evaluators/risk.py. Declarative policies live in policies/authentication_policy.yaml, policies/device_policy.yaml, and policies/risk_policy.yaml. Device posture/trust is evaluated in app/security/device/trust_evaluator.py; adaptive risk is calculated in app/security/adaptive/risk_engine.py. Relationship-aware checks are isolated in app/security/graph/relationship_graph.py.
Grants, Tokens, and Federation Boundaries
Successful decisions may produce scoped grants and tokens. Grant issuance/validation/storage are separated in app/security/grants/issuer.py, app/security/grants/validator.py, and app/security/grants/store.py; service-facing orchestration is in app/services/grant_service.py. Token construction and enforcement reside in app/security/tokens/issuer.py and app/security/tokens/enforce.py. Federation supports discovery, JWKS, JWT construction, signature verification, replay protection, and revocation through app/security/federation/service.py, app/security/federation/verifier.py, and app/security/federation/replay_store_redis.py.
Evidence, Audit, and Persistence
Authoritative decisions are coupled to append-oriented evidence generation and verification: app/security/evidence/engine.py, app/security/evidence/writer.py, and app/security/evidence/verify.py. Evidence supports hot/cold/replay memory tiers and PostgreSQL storage (app/security/evidence/memory/tier.py, app/security/evidence/postgres_store.py). Database models/session management are in app/db/models.py and app/db/session.py, with Alembic and SQL migrations under alembic/env.py and migrations/. Observability is non-authoritative and exported via app/security/observability/emitter.py, with SIEM/SOAR sinks in app/security/observability/sinks/siem.py and app/security/observability/sinks/soar.py.
High-Assurance Track D
app/security/track_d/ is a distinct verification and transparency subsystem: Merkle logs (track_d/merkle/tree.py), consensus/quorum (track_d/consensus/quorum_engine.py), anchoring (track_d/anchoring/multi_anchor_client.py), and public verification (track_d/public_verify/root_verifier.py). It supports Ed25519, threshold signing, and pluggable HSM/PKCS#11 providers under track_d/signing/. SQLite is available for this subsystem via track_d/storage/sqlite_backend.py; Redis and PostgreSQL are the other explicit infrastructure integrations.
Main entry points: pipeline.py Enforcement pipeline · auth.py Auth and WebAuthn routes · auth_service.py Authentication service · engine.py Evidence engine
Components 21
HTTP entry
- HTTP application
app/main.py - Auth and WebAuthn routes
app/api/auth.py
Decision enforcement
- Security middleware
app/security/middleware.py - Enforcement pipeline · Fail-closed decision coordination.
app/security/pipeline.py - Runtime engine
app/security/runtime/engine.py - Policy engine
app/security/policy/engine.py - Policy evaluators · Independent device, adaptive-risk, and relationship inputs.
app/security/policy/evaluators/device.py - Declarative policies
policies/authentication_policy.yaml
Identity and credentials
- Authentication service
app/services/auth_service.py - Session service
app/services/session_service.py - WebAuthn ceremony · Challenge, attestation, assertion, and credential mapping flow.
app/security/webauthn/challenge.py - Device service
app/services/device_service.py - Device models
app/db/device_models.py
Grants and federation
- Grant service
app/services/grant_service.py - Grant issuer and store · Issues, validates, and stores scoped grants.
app/security/grants/issuer.py - Token issuer and enforcement
app/security/tokens/issuer.py - Federation service · Discovery, JWT verification, replay protection, and revocation.
app/security/federation/service.py
Evidence and assurance
- Evidence engine · Authoritative decisions append verifiable evidence.
app/security/evidence/engine.py - Evidence tiers and PostgreSQL · Hot/cold/replay memory tiers with PostgreSQL storage.
app/security/evidence/memory/tier.py - Track D transparency · Merkle, quorum, anchoring, and public root verification.
- Observability emitter · Exports events to SIEM and SOAR sinks.
app/security/observability/emitter.py
Connections 21
- HTTP application → Auth and WebAuthn routes: serves
- Auth and WebAuthn routes → Authentication service: delegates lifecycle
- Auth and WebAuthn routes → WebAuthn ceremony: routes ceremonies
- HTTP application → Security middleware: applies
- Security middleware → Enforcement pipeline: enforces request
- Enforcement pipeline → Runtime engine: executes through
- Runtime engine → Policy engine: requests decision
- Policy engine → Policy evaluators: evaluates inputs
- Declarative policies → Policy engine: defines rules
- Authentication service → Session service: manages sessions
- Authentication service → WebAuthn ceremony: uses credentials
- Device service → Device models: persists lifecycle
- Policy evaluators → Device service: consults posture
- Enforcement pipeline → Evidence engine: records authoritative decision
- Evidence engine → Evidence tiers and PostgreSQL: appends and verifies
- Evidence engine → Track D transparency: anchors transparency proof
- Enforcement pipeline → Grant service: permits issuance
- Grant service → Grant issuer and store: orchestrates
- Grant issuer and store → Token issuer and enforcement: scopes token
- Token issuer and enforcement → Federation service: federates
- Enforcement pipeline → Observability emitter: emits telemetry · Telemetry is not authoritative.