Signal Identity Module

Backend-only identity integration module for the Signal Framework. This package provides secure, transport-agnostic authentication orchestration for OAuth and OIDC style providers, plus a clean extension interface for custom providers.

Purpose

• Normalize external provider identities into a consistent auth model.
• Provide secure auth flow orchestration without tying to a web framework.
• Offer clear boundaries and ports for persistence, crypto, HTTP, and logging.

Features

• Built-in providers: Google, Apple, LinkedIn, GitHub, Facebook.
• Pluggable provider interface for custom integrations.
• Stateful auth orchestration with PKCE and nonce support.
• Safe account resolution, linking, and unlinking with guardrails.
• Transport-agnostic Signal capability handlers.
• Typed results and structured errors.
• In-memory adapters for tests and reference use.

Architecture Overview

• Domain: core models, errors, and events.
• Application: auth orchestration, config validation, provider registry.
• Providers: built-in and custom provider implementations.
• Ports: persistence, crypto, HTTP, logging, time.
• Adapters: in-memory stores, system crypto, fetch HTTP client.
• Signal: capability definitions and handler wrappers.

See docs/ARCHITECTURE.md for details.

Install

This module is intended to be used within the Signal Framework workspace.

pnpm -C server/identity install

Configuration

import { createAuthService } from './src/application/auth-service';
import { createDefaultProviderRegistry } from './src/application/provider-registry';
import {
  MemoryAuthStateRepository,
  MemoryProviderAccountRepository,
  MemoryTokenStore,
  MemoryUserRepository,
  MemoryAuditEventRepository,
  MemoryEventPublisher,
} from './src/adapters/memory/repositories';
import { NodeCryptoAdapter } from './src/adapters/system/node-crypto';
import { SystemClock } from './src/adapters/system/clock';
import { FetchHttpClient } from './src/adapters/http/fetch-client';

const registry = createDefaultProviderRegistry();

const config = {
  providers: {
    google: {
      enabled: true,
      clientId: process.env.GOOGLE_CLIENT_ID ?? '',
      clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? '',
      redirectUri: 'https://api.example.com/auth/google/callback',
      scopes: ['openid', 'email', 'profile'],
    },
  },
  policy: {
    allowEmailMatch: true,
    autoCreateUser: true,
    autoLink: true,
    requireVerifiedEmail: true,
  },
};

const result = createAuthService({
  registry,
  config,
  userRepo: new MemoryUserRepository(),
  providerAccountRepo: new MemoryProviderAccountRepository(),
  authStateRepo: new MemoryAuthStateRepository(),
  tokenStore: new MemoryTokenStore(),
  auditRepo: new MemoryAuditEventRepository(),
  eventPublisher: new MemoryEventPublisher(),
  crypto: new NodeCryptoAdapter(),
  clock: new SystemClock(),
  httpClient: new FetchHttpClient(),
});

if (!result.ok) {
  throw new Error(result.error.message);
}

const authService = result.value;

Built-in Providers

• Google: OAuth 2.0 + OIDC profile mapping.
• Apple: OAuth 2.0 with issuer-aware configuration.
• LinkedIn: OAuth 2.0 basic profile mapping.
• GitHub: OAuth 2.0 user profile mapping.
• Facebook: OAuth 2.0 profile mapping.

Each provider isolates endpoints, config validation, and profile normalization. See src/providers/builtins.

Custom Provider Plugin Example

See examples/providers/enterprise-oidc.ts for a generic OIDC provider implementation and registration.

Signal Integration Example

import { createSignalHandlers } from './src/signal/handlers';

const handlers = createSignalHandlers(authService);

const authorize = handlers['auth.provider.authorize.v1'];
const result = await authorize({
  provider: 'google',
  redirectUri: 'https://api.example.com/auth/google/callback',
});

Security Model

• CSRF-resistant state handling with TTL.
• PKCE support with strict verifier checks.
• Nonce handling for replay protection.
• Strict redirect URI matching by default.
• Tokens are never logged and are stored via a port interface.
• Constant-time comparisons for secret material.

See docs/SECURITY.md for details.

Testing and Coverage

pnpm -C server/identity test:coverage

Coverage gates are enforced at 100% for statements, branches, functions, and lines.

Limitations

• This module does not implement UI flows or browser sessions.
• Provider SDKs are intentionally not included; HTTP is abstracted.
• Database adapters are not included; ports are provided for integration.

Future Extension Points

• Multi-tenant account routing strategies.
• Token revocation support per provider.
• Additional provider adapters (OIDC discovery, SAML bridges).
• Rate limiting and risk scoring policies.

License

See repository license.