@alphamatica/hub-sdk-nest

NestJS integration for alpha-hub trust-headers SDK.

In the alpha-hub architecture all browser→service traffic is proxied through alpha-hub core. The hub validates JWT and resolves permissions at edge, then forwards the request to your service with X-Alpha-User-* headers and a shared X-Alpha-Proxy-Secret. This package verifies the proxy secret and parses the user headers into req.alphaUser.

Your service does NOT need to know about hub URL, JWT public key, or catalog endpoints. Only the shared proxy secret.

Install

pnpm add @alphamatica/hub-sdk-nest

Quick wire-up

// app.module.ts
import { Module } from '@nestjs/common';
import { AlphaTrustModule, AlphaTrustGuard, RequirePermissionGuard } from '@alphamatica/hub-sdk-nest';
import { APP_GUARD } from '@nestjs/core';

@Module({
  imports: [
    AlphaTrustModule.forRoot({
      proxySecret: process.env.ALPHA_PROXY_SECRET!,
    }),
  ],
  providers: [
    // Apply globally so every route is trust-checked + permission-checked.
    // Routes without @RequirePermission just need a valid proxy secret + user headers.
    { provide: APP_GUARD, useClass: AlphaTrustGuard },
    { provide: APP_GUARD, useClass: RequirePermissionGuard },
  ],
})
export class AppModule {}

Then on controllers:

import { Controller, Get } from '@nestjs/common';
import { RequirePermission, AlphaUser } from '@alphamatica/hub-sdk-nest';
import type { AlphaUserShape } from '@alphamatica/hub-sdk-nest';

@Controller('playlists')
export class PlaylistsController {
  @Get()
  @RequirePermission('asur.playlists.read')
  list(@AlphaUser() user: AlphaUserShape) {
    // user.id, user.email, user.scopes available
    return this.svc.list({ scopes: user.scopes });
  }
}

Environment

Only one variable needed:

| Variable | Description | |---|---| | ALPHA_PROXY_SECRET | Shared secret with alpha-hub. The hub sets this in its env and includes it as X-Alpha-Proxy-Secret on every forwarded request. Generate with openssl rand -hex 32. |

No ALPHA_HUB_URL, no public key, no sync secret.

Architecture note

Requests reach your service ONLY through alpha-hub's /proxy/:serviceId/* forwarder. The hub does:

1. JWT validation
2. Permission resolution (role → permissions catalog)
3. Audit logging
4. Forward request + headers to your service

Your service trusts the forwarded headers (verified via X-Alpha-Proxy-Secret) and applies @RequirePermission checks against the already-resolved permission set in the header.

For defense-in-depth, also restrict your service to internal network so it's unreachable bypassing hub. The proxy secret is the auth-header-level guarantee; network isolation is the topology-level guarantee.

Migrating from v0.1.x

v0.1.x had AlphaAuthModule.forRoot({ coreUrl, serviceId, publicKey, syncSecret, ... }). v0.2.0 collapses all that to:

AlphaTrustModule.forRoot({ proxySecret: ... })

AlphaAuthGuard → AlphaTrustGuard. @RequirePermission and @AlphaUser keep the same name and semantics. Sync endpoints (/alpha-sync/*) and SSO bridge are gone — hub proxy handles those flows now.