Skip to main content

@cortexa/auth

Project Overview​

@cortexa/auth is a reusable TypeScript library for external OAuth authentication infrastructure in the Cortexa ecosystem.

It exists to keep provider-specific OAuth behavior out of consuming applications while giving those applications a consistent in-process API for connecting external accounts, retrieving valid access sessions, refreshing expired credentials, and disconnecting accounts.

This repository is for Cortexa services, Node.js and TypeScript applications, and storage adapter authors that need normalized external OAuth account and session handling. It is not a hosted authentication service, browser UI, HTTP callback handler, first-party user system, or authorization policy layer.

Key Responsibilities​

  • Define provider-neutral contracts for external auth accounts, sessions, providers, account lookup, and storage.
  • Provide an AuthService orchestration layer for common external account lifecycle flows.
  • Isolate provider-specific OAuth integration behind provider adapters.
  • Include Google OAuth support as the current provider implementation.
  • Provide a volatile in-memory storage adapter for local, test, and non-production scenarios.
  • Export typed auth errors and public package APIs for consuming applications.

Current Status​

Implemented capabilities:

  • TypeScript package structure with src/ as the source of record and dist/ as compiler output.
  • Provider-neutral core auth contracts and session expiration helper.
  • Google OAuth provider adapter using googleapis.
  • Storage adapter contract and in-memory storage implementation.
  • AuthService flows for auth URL generation, account connection, account lookup, valid session retrieval, refresh, and disconnect.
  • Auth-specific error types.
  • Minimal Google usage example under examples/.

Planned or incomplete capabilities:

  • Google provider revocation is part of the provider contract but is not implemented as a working capability.
  • No concrete roadmap items for additional providers, durable storage adapters, HTTP routes, UI, or production persistence are documented. The architecture defines extension points for those concerns, but consumer applications currently own production persistence, routing, user identity, and authorization.

Getting Started​

Start with the package metadata and public entrypoint:

  • package.json identifies the package, dependencies, and scripts.
  • src/index.ts shows the public API surface intended for consumers.
  • examples/google-auth.ts demonstrates composing the Google provider with environment-backed configuration.

Common local commands:

npm install
npm run build
npm run dev

Key technologies:

  • TypeScript
  • Node.js
  • googleapis
  • dotenv for example runtime configuration

Before changing structure or public contracts, read the architecture and repository guides under docs/.

Documentation​

  • docs/ARCHITECTURE.md: architectural source of truth for repository purpose, ecosystem role, boundaries, responsibilities, contracts, constraints, and design principles.
  • docs/REPOSITORY.md: repository organization source of truth for folder responsibilities, module placement, dependency direction, and code placement guidance.
  • examples/google-auth.ts: compact usage example for Google auth URL generation.

Additional long-lived documentation should live under docs/ and be linked from this README when it becomes part of the repository documentation corpus.

Architecture Summary​

The package follows a small ports-and-adapters design. Core auth contracts remain provider-neutral, provider adapters isolate external SDK behavior, storage adapters define persistence boundaries, and AuthService coordinates flows without owning provider-specific or database-specific implementation details.

For architectural details, invariants, and integration boundaries, see docs/ARCHITECTURE.md.

Repository Organization Summary​

The repository is a single-package TypeScript library. Source code lives under src/, examples live under examples/, and long-lived documentation lives under docs/. Generated build output belongs in dist/ and should not be treated as source of record.

For repository navigation, module responsibilities, and code placement rules, see docs/REPOSITORY.md.

Contributing​

Contributors should follow the existing package boundaries and source conventions:

  • Keep core contracts provider-neutral and storage-neutral.
  • Keep provider SDK usage inside provider-specific folders.
  • Keep consumer-owned concerns such as HTTP routing, user identity, tenant ownership, production persistence, and authorization policy outside this package unless the architecture is intentionally changed.
  • Add consumer-facing exports through src/index.ts.
  • Keep documentation aligned with implementation when changing behavior, structure, or public contracts.

Read docs/ARCHITECTURE.md and docs/REPOSITORY.md before making structural changes.

Documentation Philosophy​

README.md is the repository entrypoint. It should remain concise, readable, and useful as a quick onboarding guide for humans and AI systems.

docs/ARCHITECTURE.md is the architectural source of truth.

docs/REPOSITORY.md is the repository organization source of truth.

Detailed architectural explanations, repository navigation, implementation notes, API details, database guidance, and other long-form documentation belong under docs/, not in this README.