@eminuckan/spine 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-03-15
+
+### Added
+
+- Added framework-agnostic permission route protection primitives.
+- Added configurable tenant cookie policy in core.
+- Added generic server-side identity context resolution helpers.
+- Added React Router adapter entry points.
+- Added open source contributor documentation, security policy, and repository scaffolding.
+
+### Changed
+
+- Moved tenant, identity, and permission server orchestration out of the dashboard app and into Spine.
+- Expanded tenant primitives to support membership-aware state.
+- Updated package metadata for a fresh public open source release.
+- Rewrote README around the current adapter-based architecture.
+- Renamed remaining package-level branding defaults from legacy product names to Spine-oriented names where appropriate.
+
+## [0.1.16] - 2026-02-28
+
+### Changed
+
+- Switched publishing target to npmjs.org with public access.
+- Updated README package references and publishing instructions for npm public releases.
+- Included `LICENSE` in published package files.
+
+## [0.1.2] - 2025-12-05
+
+### Added
+
+- Added `REDIS_KEY_PREFIX` support for Redis session storage.
+
+## [0.1.1] - 2025-12-05
+
+### Fixed
+
+- Fixed author field encoding issue in `package.json`.
+
+## [0.1.0] - 2025-12-04
+
+### Added
+
+- Initial release of Spine.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Muhammet Emin Üçkan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,425 @@
+# Spine
+
+Framework-agnostic SaaS primitives for authentication, identity, permissions, multi-tenancy, API access, realtime events, query configuration, and logging.
+
+Spine is designed around one idea: the reusable parts of a SaaS platform should live in a single package, while application policy and framework quirks should stay in thin adapters. Today the package ships a framework-agnostic core plus a React Router adapter surface. Future adapters can follow the same pattern.
+
+## Status
+
+- Core package: `@eminuckan/spine`
+- Current adapter: `@eminuckan/spine/react-router`
+- Server primitives use Web `Request`/`Response` objects, not framework-specific response helpers
+- React Router adapter is intentionally thin today so other adapters can be added without changing the core contract
+
+## Why Spine
+
+Most internal app infrastructure starts the same way: one product grows an auth layer, a tenant switcher, permission checks, a query client, an API wrapper, and a realtime client. Then a second product appears and copies all of it. Spine exists to stop that drift.
+
+Spine aims to be:
+
+- Framework-agnostic at its core
+- Adapter-friendly for framework integration
+- Config-driven for backend conventions
+- Honest about boundaries between reusable primitives and app-specific policy
+- Small enough to understand, flexible enough to extend
+
+## Design Principles
+
+- Core before adapter: framework-specific behavior belongs in dedicated adapter entry points
+- Configure, do not fork: backend claim names, cookie behavior, endpoints, and redirects should be configured first
+- Request/Response first: server modules should work anywhere a standard Web `Request` and `Response` exist
+- App policy stays local: onboarding flows, subscription gates, product-specific redirects, and permission taxonomies should live in the consuming app
+- Open for composition: apps should be able to wrap Spine primitives instead of rewriting them
+
+## Package Surfaces
+
+| Entry point | Purpose |
+| --- | --- |
+| `@eminuckan/spine` | Client-side primitives and shared types |
+| `@eminuckan/spine/server` | Framework-agnostic server primitives |
+| `@eminuckan/spine/react-router` | React Router client adapter |
+| `@eminuckan/spine/react-router/server` | React Router server adapter |
+| `@eminuckan/spine/auth` | Auth types |
+| `@eminuckan/spine/auth/server` | Auth/session/route protection primitives |
+| `@eminuckan/spine/tenant` | Tenant store, provider, and types |
+| `@eminuckan/spine/tenant/server` | Tenant cookie and server helpers |
+| `@eminuckan/spine/identity` | Identity store/provider/types |
+| `@eminuckan/spine/identity/server` | Identity context cache and server orchestration |
+| `@eminuckan/spine/api-client` | Client-side API types and errors |
+| `@eminuckan/spine/api-client/server` | Server-side API config and Axios helpers |
+| `@eminuckan/spine/permissions` | Client-side permission primitives |
+| `@eminuckan/spine/logging` | Logging primitives |
+| `@eminuckan/spine/query-client` | TanStack Query helpers |
+| `@eminuckan/spine/signalr` | Realtime client helpers |
+
+## What Spine Includes
+
+- OAuth2/OIDC login, callback handling, logout, and token refresh
+- Redis-backed session and OAuth state storage
+- Server-side route protection primitives
+- Server-side permission route protection configuration
+- Multi-tenant client state and server helpers
+- Identity context cache, fetch orchestration, and client store/provider
+- API client factory and Axios interceptor setup
+- TanStack Query client defaults and cache presets
+- SignalR client helpers
+- Logging primitives
+
+## What Spine Does Not Include
+
+- Your product's onboarding rules
+- Your product's subscription rules
+- Your product's permission vocabulary
+- Your backend DTOs or generated API clients
+- Your page structure, layouts, or UI system
+
+Those belong in the consuming app or in a product-specific adapter package.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A["Spine"] --> B["Server Primitives"]
+  A --> C["Client Primitives"]
+  B --> D["Framework Adapter"]
+  C --> D
+  D --> E["Application Adapter Layer"]
+  E --> F["Product UI + Backend APIs"]
+```
+
+The important boundary is between reusable infrastructure and product policy:
+
+- Spine owns generic primitives
+- Framework adapters own framework glue
+- Application adapters own product-specific routing, claims, endpoints, and workflow rules
+
+Detailed architecture notes live in [docs/architecture.md](docs/architecture.md).
+
+## Installation
+
+```bash
+pnpm add @eminuckan/spine
+```
+
+If you use client-side React features, install peer dependencies too:
+
+```bash
+pnpm add react @tanstack/react-query
+```
+
+## Environment Variables
+
+The built-in auth/session layer currently reads these environment variables:
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `OIDC_AUTHORITY` | Yes | OAuth/OIDC issuer base URL |
+| `OIDC_CLIENT_ID` | Yes | Client identifier |
+| `OIDC_REDIRECT_URI` | Yes | OAuth callback URL |
+| `OIDC_CLIENT_SECRET` | No | Client secret for confidential clients |
+| `OIDC_SCOPE` | No | Requested scope string |
+| `OIDC_POST_LOGOUT_REDIRECT_URI` | No | Logout return URL |
+| `OIDC_APPLICATION_TYPE` | No | `no-landing-page`, `landing-page`, or legacy aliases |
+| `OIDC_SSO_LOGOUT` | No | Explicit full-logout override |
+| `OIDC_HAS_LANDING_PAGE` | No | Explicit landing-page behavior override |
+| `REDIS_URL` | No | Redis connection string for sessions and OAuth state |
+| `REDIS_KEY_PREFIX` | No | Prefix for Redis keys |
+| `API_BASE_URL` | No | Default API base URL for `createAPIConfigFactory` |
+
+## Quick Start
+
+### 1. Configure Identity and Tenant Adapters
+
+Spine's server modules are generic, so your app should provide backend-specific fetchers once.
+
+```ts
+// app/lib/mimir/identity.server.ts
+import {
+  configureIdentityAPIFetcher,
+  configurePermissionFetcher,
+  contextToUserInfo,
+  getIdentityContext,
+} from '@eminuckan/spine/identity/server';
+import { createAPIConfigFactory } from '@eminuckan/spine/api-client/server';
+import { getAccessToken } from '@eminuckan/spine/react-router/server';
+import { getCurrentTenant } from '@eminuckan/spine/tenant/server';
+import { Configuration, IdentityApi } from '~/lib/api-clients/api';
+
+const { createAPIConfig } = createAPIConfigFactory(getAccessToken, getCurrentTenant);
+
+configureIdentityAPIFetcher(async (request) => {
+  const config = await createAPIConfig(request, {
+    requireTenant: false,
+    includeAuth: true,
+  });
+
+  const api = new IdentityApi(
+    new Configuration({
+      basePath: config.basePath,
+      accessToken: config.accessToken,
+      baseOptions: { headers: config.headers },
+    })
+  );
+
+  const response = await api.identityGetMyContext();
+
+  return {
+    ...response.data,
+    contextVersion: Date.now(),
+    hasSubscription: Boolean(
+      response.data.onboarding?.subscription?.exists &&
+      ['active', 'trialing'].includes(response.data.onboarding?.subscription?.status || '')
+    ),
+  };
+});
+
+configurePermissionFetcher(async (request, tenantId) => {
+  const config = await createAPIConfig(request, { requireTenant: false });
+  const api = new IdentityApi(
+    new Configuration({
+      basePath: config.basePath,
+      accessToken: config.accessToken,
+      baseOptions: { headers: config.headers },
+    })
+  );
+
+  const response = await api.identityGetMyPermissions(tenantId);
+  return response.data.permissions || [];
+});
+
+export { contextToUserInfo, getIdentityContext };
+```
+
+```ts
+// app/lib/mimir/tenant.server.ts
+import {
+  configureIdentityContextFetcher,
+  configureTenantCookie,
+  getAvailableTenants,
+  getCurrentTenant,
+  initializeTenant,
+} from '@eminuckan/spine/tenant/server';
+import { fetchIdentityContext } from './identity.server';
+
+configureTenantCookie({
+  httpOnly: false,
+  sameSite: 'Lax',
+});
+
+configureIdentityContextFetcher(fetchIdentityContext);
+
+export {
+  getAvailableTenants,
+  getCurrentTenant,
+  initializeTenant,
+};
+```
+
+### 2. Configure Server-Side Permission Protection
+
+```ts
+// app/lib/mimir/permissions.server.ts
+import {
+  configurePermissionRouteProtection,
+  requirePermission,
+} from '@eminuckan/spine/server';
+import { getAuthSession } from '@eminuckan/spine/react-router/server';
+import { contextToUserInfo, getIdentityContext } from './identity.server';
+import { getCurrentTenant } from './tenant.server';
+
+configurePermissionRouteProtection({
+  getSession: getAuthSession,
+  resolveContext: async (request, session) => {
+    if (!session.user?.sub) {
+      return { permissions: [], currentTenant: null };
+    }
+
+    const identityContext = await getIdentityContext(request, session.user.sub);
+    const currentTenant = await getCurrentTenant(request);
+    const userInfo = await contextToUserInfo(identityContext, {
+      currentTenant,
+      request,
+    });
+
+    return {
+      permissions: userInfo.permissions,
+      currentTenant: userInfo.currentTenant,
+    };
+  },
+});
+
+export { requirePermission };
+```
+
+### 3. Protect Routes
+
+```ts
+// app/routes/_protected.tsx
+import { authRoute, getAccessToken } from '@eminuckan/spine/react-router/server';
+import { getCurrentTenant, initializeTenant } from '~/lib/mimir/tenant.server';
+import { contextToUserInfo, getIdentityContext } from '~/lib/mimir/identity.server';
+
+export async function loader({ request }: { request: Request }) {
+  return authRoute(request, async (user) => {
+    const [accessToken, identityContext, currentTenant] = await Promise.all([
+      getAccessToken(request),
+      getIdentityContext(request, user.sub),
+      getCurrentTenant(request),
+    ]);
+
+    const initResult =
+      !currentTenant && identityContext.hasAnyMembership
+        ? await initializeTenant(request)
+        : null;
+
+    const userInfo = await contextToUserInfo(identityContext, {
+      currentTenant: initResult?.tenantId ?? currentTenant,
+      request,
+    });
+
+    return {
+      user,
+      accessToken,
+      identity: {
+        ...identityContext,
+        permissions: userInfo.permissions,
+        currentTenant: userInfo.currentTenant,
+      },
+      tenantHeaders: initResult?.headers ?? null,
+    };
+  });
+}
+```
+
+### 4. Wire Client Providers
+
+```tsx
+import { QueryClientProvider } from '@tanstack/react-query';
+import {
+  TenantProvider,
+  IdentityContextProvider,
+  PermissionInitializer,
+  createQueryClient,
+} from '@eminuckan/spine';
+
+const queryClient = createQueryClient();
+
+export function AppProviders({
+  children,
+  tenant,
+  identity,
+  accessToken,
+}: {
+  children: React.ReactNode;
+  tenant: { currentTenant: string | null; availableTenants: string[]; memberships: any[] };
+  identity: { permissions: string[]; isLoading?: boolean } & Record<string, unknown>;
+  accessToken?: string | null;
+}) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <TenantProvider
+        initialTenant={tenant.currentTenant}
+        initialTenants={tenant.availableTenants}
+        initialMemberships={tenant.memberships}
+      >
+        <IdentityContextProvider
+          initialContext={identity}
+          accessToken={accessToken}
+        >
+          <PermissionInitializer
+            permissions={identity.permissions as string[]}
+            isLoading={Boolean(identity.isLoading)}
+          >
+            {children}
+          </PermissionInitializer>
+        </IdentityContextProvider>
+      </TenantProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### 5. Configure Backend Conventions Instead of Forking
+
+```ts
+import {
+  configureAuthClaimMapping,
+  configureIdentityStore,
+  configureRouteProtection,
+} from '@eminuckan/spine/server';
+
+configureAuthClaimMapping({
+  tenantIds: ['organizations', 'tenant_ids'],
+  tenantRoles: ['organization_roles', 'tenant_roles'],
+  permissions: ['permissions', 'scope'],
+  isOnboarded: ['profile_complete', 'is_onboarded'],
+});
+
+configureIdentityStore({
+  contextEndpoint: '/api/me/context',
+  permissionsEndpoint: '/api/me/permissions',
+  logoutPath: '/session/logout',
+});
+
+configureRouteProtection({
+  getLoginReturnUrl: ({ request }) => new URL(request.url).pathname,
+});
+```
+
+More adaptation examples live in [docs/backend-adaptation.md](docs/backend-adaptation.md).
+
+## Module Guides
+
+- [Architecture](docs/architecture.md)
+- [Adapters](docs/adapters.md)
+- [Backend Adaptation](docs/backend-adaptation.md)
+- [Module Reference](docs/module-reference.md)
+- [Releasing](docs/releasing.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+
+## Current Boundaries
+
+Spine already owns the reusable infrastructure for:
+
+- Session lifecycle
+- OAuth state and token refresh
+- Tenant state and tenant cookie handling
+- Identity cache and permission resolution
+- Permission route protection
+- API client setup
+
+Consuming apps should still own:
+
+- Product-specific onboarding pages and redirects
+- Product-specific subscription policies
+- Permission constants and domain vocabulary
+- Generated API clients
+- UI-specific wrappers and design system components
+
+## Roadmap
+
+- First-class Next.js adapter surface
+- More adapter authoring guidance
+- Cleaner permission taxonomy extension story
+- More example apps
+- Broader runtime coverage tests
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm build
+pnpm lint
+```
+
+Detailed contributor guidance lives in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Versioning
+
+Spine currently uses semver with a `0.x` release line. Breaking changes can still happen more frequently than a mature `1.x` package, but they should be documented in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/api-client/index.d.ts

@@ -0,0 +1,3 @@
+import "../types-BTjFzIhv.js";
+import { APIConfig, APILogger, ApiError$1 as ApiError, CreateAPIConfigOptions, ErrorCodes$1 as ErrorCodes, ErrorHandler$1 as ErrorHandler, GetAccessTokenFn, GetCurrentTenantFn, ProblemDetails, RetryConfig, TokenRefreshFn, TokenRefreshResult, ValidationError, calculateBackoffDelay$1 as calculateBackoffDelay, createRetryFetch$1 as createRetryFetch, fetchWithTimeout$1 as fetchWithTimeout, handleApiError$1 as handleApiError, isRetryableError$1 as isRetryableError, withRetry$1 as withRetry } from "../index-D6RK_5vm.js";
+export { APIConfig, APILogger, ApiError, CreateAPIConfigOptions, ErrorCodes, ErrorHandler, GetAccessTokenFn, GetCurrentTenantFn, ProblemDetails, RetryConfig, TokenRefreshFn, TokenRefreshResult, ValidationError, calculateBackoffDelay, createRetryFetch, fetchWithTimeout, handleApiError, isRetryableError, withRetry };

package/dist/api-client/index.js

@@ -0,0 +1,4 @@
+import "../logging-_h2mi3L9.js";
+import { ApiError, ErrorCodes, ErrorHandler, calculateBackoffDelay, createRetryFetch, fetchWithTimeout, handleApiError, isRetryableError, withRetry } from "../api-client-Ftxqm3Ep.js";
+
+export { ApiError, ErrorCodes, ErrorHandler, calculateBackoffDelay, createRetryFetch, fetchWithTimeout, handleApiError, isRetryableError, withRetry };

package/dist/api-client/server.d.ts

@@ -0,0 +1,4 @@
+import "../types-BTjFzIhv.js";
+import { APIConfig, APILogger, ApiError$1 as ApiError, CreateAPIConfigOptions, ErrorCodes$1 as ErrorCodes, ErrorHandler$1 as ErrorHandler, GetAccessTokenFn, GetCurrentTenantFn, ProblemDetails, RetryConfig, TokenRefreshFn, TokenRefreshResult, ValidationError, calculateBackoffDelay$1 as calculateBackoffDelay, createRetryFetch$1 as createRetryFetch, fetchWithTimeout$1 as fetchWithTimeout, handleApiError$1 as handleApiError, isRetryableError$1 as isRetryableError, withRetry$1 as withRetry } from "../index-D6RK_5vm.js";
+import { APIConfigFactory, APIConfigFactoryOptions, AxiosSetupOptions, CreateEnhancedClientOptions, createAPIConfigFactory$1 as createAPIConfigFactory, createEnhancedClient$1 as createEnhancedClient, setupAxiosInterceptors$1 as setupAxiosInterceptors } from "../server-CLbksnvg.js";
+export { APIConfig, APIConfigFactory, APIConfigFactoryOptions, APILogger, ApiError, AxiosSetupOptions, CreateAPIConfigOptions, CreateEnhancedClientOptions, ErrorCodes, ErrorHandler, GetAccessTokenFn, GetCurrentTenantFn, ProblemDetails, RetryConfig, TokenRefreshFn, TokenRefreshResult, ValidationError, calculateBackoffDelay, createAPIConfigFactory, createEnhancedClient, createRetryFetch, fetchWithTimeout, handleApiError, isRetryableError, setupAxiosInterceptors, withRetry };

package/dist/api-client/server.js

@@ -0,0 +1,5 @@
+import "../logging-_h2mi3L9.js";
+import { ApiError, ErrorCodes, ErrorHandler, calculateBackoffDelay, createRetryFetch, fetchWithTimeout, handleApiError, isRetryableError, withRetry } from "../api-client-Ftxqm3Ep.js";
+import { createAPIConfigFactory, createEnhancedClient, setupAxiosInterceptors } from "../server-DLgH3FRR.js";
+
+export { ApiError, ErrorCodes, ErrorHandler, calculateBackoffDelay, createAPIConfigFactory, createEnhancedClient, createRetryFetch, fetchWithTimeout, handleApiError, isRetryableError, setupAxiosInterceptors, withRetry };