logicspike/docs

Authentication & Team

LogicSpike Auth & PBAC Architecture

Last Updated: 2026-03-30 Status: Active

This document provides a comprehensive technical breakdown of how authentication, authorization, and Permission-Based Access Control (PBAC) operate within the LogicSpike platform. It serves as the primary architecture spec for engineering.

1. Architecture Overview

The LogicSpike authorization system operates on a "Zero DB Calls for Authorization" philosophy. To achieve minimal latency at the edge, all user permissions, roles, and enabled services are aggressively encoded into the JWT (JSON Web Token) payload.

1.1 Key Principles

  • JSON Web Tokens (RS256): The Manager issues asymmetric JWTs. The Gateway purely verifies signatures using the public key—it does not call the Manager to validate tokens.
  • Granular Permissions (PBAC): Roles (e.g., role_owner) exist only to group permissions. Access checks evaluate explicit granular strings (e.g., blog:posts.create).
  • Edge Enforcement: The API Gateway acts as the zero-trust boundary. No public traffic reaches microservices bypassing the Cloudflare worker.

2. Permission-Based Access Control (PBAC)

2.1 Format Convention

All permissions are strictly defined in packages/core-access/src/permission-catalogue.ts and MUST follow the service:resource.action syntax.

Segment Meaning Example
service The owning microservice namespace blog
resource Plural entity being accessed posts
action The CRUD/business operation read, write, manage

IMPORTANT

A master bypass string system:owner exists. Any user holding this string automatically passes all requirePermission backend checks.

2.2 JWT Payload Injection

Upon successful authentication or workspace swap, the Manager service bundles the user's authorized state into the JWT payload:

{
  "user_id": "usr_123",
  "tenant_id": "tnt_456",
  "role": "role_owner",
  "permissions": [
    "system:owner",
    "blog:posts.read",
    "media:files.write"
  ],
  "services": {
    "blog": { "enabled": true },
    "media": { "enabled": true }
  }
}

3. Gateway Enforcement Flow

The apps/gateway Cloudflare Worker sits in front of all backend traffic.

3.1 Context Finalization Rules

When writing routing middleware (authMiddleware) in the Hono-based Gateway:

WARNING

Branching logic that throws HTTP 401s must bubble up the response via return await authMiddleware(c, next). Dropping the response object causes Hono to throw a misleading 500 Context is not finalized crash.

3.2 Public Route Bypassing

If an endpoint is strictly public (like /permissions/catalog), it requires a dual-bypass:

  1. Marked in the Gateway isStaticPublic array.
  2. Verified with the GATEWAY_BYPASS_PATHS within the local microservice.

4. NextAuth Frontend Sync

The frontend apps/seller-dashboard heavily relies on NextAuth (next-auth) to hydrate visual session states.

  1. User submits credentials to POST /auth/login.
  2. The Manager explicitly returns { permissions, role, services } in the JSON body payload.
  3. The NextAuth authorize() callback reads these explicitly returned arrays to populate the NextAuth session.
  4. Subsequent React components render based on the activeSession using the <PermissionGate> wrapper.

5. API Keys and Cryptography

API keys are functionally identical to users in the eyes of backend microservices. Both merely inject an x-user-permissions array into the request headers.

5.1 Key Lifecycle

Key Type Scope Restrictions Storage
Secret Unlimited (Full PBAC suite) Hashed SHA-256 in Database
Publishable Enforced readOnly permissions only Hashed SHA-256 in Database

The backend uses timing-safe equivalence tools provided by @repo/core-auth to prevent brute force timing attacks against hashed keys and passwords.

Authentication & Team