@heyatom/bastion-client 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @heyatom/bastion-client
+
+Consumer SDK for [Bastion](https://github.com/heyatomdev/bastion), the HeyAtom identity provider.
+Replaces the `src/modules/bastion/` boilerplate every service used to copy by hand.
+
+- `@heyatom/bastion-client` — framework-free core: `JwksVerifier` (kid-indexed cache, unknown-kid refetch with cooldown, stale-on-error), `BastionHttp` (`POST /auth/client`, `POST /events`, any other route), `ServiceTokenProvider` (single-flight refresh ahead of `exp`), payload types.
+- `@heyatom/bastion-client/nest` — NestJS: `BastionModule`, `ServiceClientJwtGuard`, `BastionUserGuard`, `BastionAuditService`, `AuditInterceptor`, `@Public()`, `@RequireScope()`, `@Audit()`, `@CurrentClient()`, `@CurrentAdminUser()`.
+
+Ships CJS and ESM. Peer deps: `jose` (always), `@nestjs/common`, `@nestjs/core`, `rxjs`, `reflect-metadata` (for `/nest`).
+
+## NestJS
+
+```ts
+// app.module.ts
+import { APP_GUARD } from '@nestjs/core';
+import { BastionModule, ServiceClientJwtGuard } from '@heyatom/bastion-client/nest';
+
+@Module({
+  imports: [
+    BastionModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        baseUrl: config.getOrThrow('BASTION_URL'),
+        serviceSlug: config.getOrThrow('BASTION_APP_SLUG'),
+        apiKey: config.get('BASTION_CLIENT_API_KEY'),
+        // tenantSlug, jwksTtlMs, issuer, acceptedAppSlugs, acceptedRoles — optional
+      }),
+    }),
+  ],
+  providers: [{ provide: APP_GUARD, useClass: ServiceClientJwtGuard }],
+})
+export class AppModule {}
+```
+
+```ts
+@Controller('mail')
+export class MailController {
+  constructor(private readonly audit: BastionAuditService) {}
+
+  @Post('send')
+  @RequireScope('mail.send')
+  send(@CurrentClient() client: ServiceClientJwtPayload, @Body() dto: SendDto) {
+    // ...
+    void this.audit.write('mail.sent', { metadata: { toDomain: 'example.com' } });
+  }
+
+  @Get('/health')
+  @Public()
+  health() { return { status: 'ok' }; }
+}
+
+// Admin surface: user tokens from the console
+@Controller('admin/config')
+@UseGuards(BastionUserGuard)
+@UseInterceptors(AuditInterceptor)
+export class AdminController {
+  @Patch()
+  @Audit('config.updated', { metadata: (_result, req) => ({ keys: Object.keys(req.body as object) }) })
+  update(@CurrentAdminUser() admin: UserJwtPayload, @Body() dto: UpdateDto) { /* ... */ }
+}
+```
+
+Bastion stores app events as `<serviceSlug>.<event>` — send the bare `resource.action`.
+
+## Without NestJS
+
+```ts
+import { JwksVerifier, BastionHttp, ServiceTokenProvider } from '@heyatom/bastion-client';
+
+const verifier = new JwksVerifier({ baseUrl: process.env.BASTION_URL! });
+const payload = await verifier.verify(bearerToken); // throws BastionTokenError
+
+const http = new BastionHttp({ baseUrl: process.env.BASTION_URL! });
+const tokens = new ServiceTokenProvider(http, { apiKey, serviceSlug: 'my-service' });
+await http.writeAuditEvent(await tokens.getToken(), { event: 'thing.done' });
+```
+
+## Release
+
+Bump `version`, tag `vX.Y.Z`, push the tag. The workflow runs lint/test/build/DI smoke and publishes with provenance (`NPM_TOKEN` secret).

package/dist/cjs/core/bastion-http.d.ts

@@ -0,0 +1,32 @@
+import type { AuditEventInput, TokenResponse } from './types.js';
+export interface BastionHttpOptions {
+    baseUrl: string;
+    fetch?: typeof fetch;
+}
+export interface ClientAuthInput {
+    apiKey: string;
+    serviceSlug: string;
+    tenantSlug?: string;
+}
+/**
+ * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
+ * `JwksVerifier`. `call` is public so a service can reach any other route
+ * (e.g. `POST /auth/login` from a BFF) with the same error handling; pass the
+ * browser's IP as `X-Real-IP` on user-facing calls so Bastion's rate-limit
+ * and audit rows see the real client, not your container.
+ */
+export declare class BastionHttp {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: BastionHttpOptions);
+    call<T>(method: string, path: string, body?: unknown, init?: {
+        token?: string;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    clientAuth(input: ClientAuthInput): Promise<TokenResponse>;
+    /** `POST /events`. Bastion stores the event as `<serviceSlug>.<event>`; send the bare `resource.action`. */
+    writeAuditEvent(token: string, data: AuditEventInput): Promise<{
+        id: string;
+        createdAt: string;
+    }>;
+}

package/dist/cjs/core/bastion-http.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BastionHttp = void 0;
+const errors_js_1 = require("./errors.js");
+/**
+ * Outbound calls to Bastion. Nothing here verifies inbound tokens — that is
+ * `JwksVerifier`. `call` is public so a service can reach any other route
+ * (e.g. `POST /auth/login` from a BFF) with the same error handling; pass the
+ * browser's IP as `X-Real-IP` on user-facing calls so Bastion's rate-limit
+ * and audit rows see the real client, not your container.
+ */
+class BastionHttp {
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async call(method, path, body, init = {}) {
+        const headers = {
+            'Content-Type': 'application/json',
+            ...init.headers,
+        };
+        if (init.token)
+            headers['Authorization'] = `Bearer ${init.token}`;
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            throw new errors_js_1.BastionHttpError(res.status, err.message ?? 'Bastion error');
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    clientAuth(input) {
+        return this.call('POST', '/auth/client', input);
+    }
+    /** `POST /events`. Bastion stores the event as `<serviceSlug>.<event>`; send the bare `resource.action`. */
+    writeAuditEvent(token, data) {
+        return this.call('POST', '/events', data, { token });
+    }
+}
+exports.BastionHttp = BastionHttp;

package/dist/cjs/core/errors.d.ts

@@ -0,0 +1,11 @@
+export type TokenErrorCode = 'malformed' | 'missing_kid' | 'unknown_kid' | 'invalid';
+/** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
+export declare class BastionTokenError extends Error {
+    readonly code: TokenErrorCode;
+    constructor(code: TokenErrorCode, message: string);
+}
+/** A non-2xx answer from Bastion's HTTP API. */
+export declare class BastionHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/dist/cjs/core/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BastionHttpError = exports.BastionTokenError = void 0;
+/** Verification failure. `code` is safe to log; the message is safe to return to the caller. */
+class BastionTokenError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BastionTokenError';
+    }
+}
+exports.BastionTokenError = BastionTokenError;
+/** A non-2xx answer from Bastion's HTTP API. */
+class BastionHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'BastionHttpError';
+    }
+}
+exports.BastionHttpError = BastionHttpError;

package/dist/cjs/core/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './errors.js';
+export { JwksVerifier, type JwksVerifierOptions } from './jwks-verifier.js';
+export { BastionHttp, type BastionHttpOptions, type ClientAuthInput } from './bastion-http.js';
+export { ServiceTokenProvider } from './service-token-provider.js';

package/dist/cjs/core/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTokenProvider = exports.BastionHttp = exports.JwksVerifier = void 0;
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./errors.js"), exports);
+var jwks_verifier_js_1 = require("./jwks-verifier.js");
+Object.defineProperty(exports, "JwksVerifier", { enumerable: true, get: function () { return jwks_verifier_js_1.JwksVerifier; } });
+var bastion_http_js_1 = require("./bastion-http.js");
+Object.defineProperty(exports, "BastionHttp", { enumerable: true, get: function () { return bastion_http_js_1.BastionHttp; } });
+var service_token_provider_js_1 = require("./service-token-provider.js");
+Object.defineProperty(exports, "ServiceTokenProvider", { enumerable: true, get: function () { return service_token_provider_js_1.ServiceTokenProvider; } });

package/dist/cjs/core/jwks-verifier.d.ts

@@ -0,0 +1,35 @@
+import { type BastionJwtPayload, type BastionLogger } from './types.js';
+export interface JwksVerifierOptions {
+    /** Bastion base URL, e.g. `http://bastion:3001`. The JWKS lives at `/.well-known/jwks.json`. */
+    baseUrl: string;
+    /** How long a fetched key set is trusted before a refetch. Default 300 000 (5 min), matching Bastion's `Cache-Control`. */
+    ttlMs?: number;
+    /** Expected `iss` claim. Default `'bastion'`. Pass `null` to skip the check. */
+    issuer?: string | null;
+    logger?: BastionLogger;
+    fetch?: typeof fetch;
+}
+/**
+ * The canonical consumer of Bastion's JWKS (docs/BASTION_INTEGRATION.md):
+ * keys cached and indexed by `kid`, refetch on an unknown kid with a
+ * cooldown, stale cache served when a refetch fails. Second safety net only:
+ * Bastion publishes a key before signing with it (publish-before-use), so a
+ * correctly configured consumer should never meet an unknown kid.
+ */
+export declare class JwksVerifier {
+    private keys;
+    private fetchedAt;
+    private lastUnknownKidRefetchAt;
+    private inFlight;
+    private readonly jwksUrl;
+    private readonly ttlMs;
+    private readonly issuer;
+    private readonly logger;
+    private readonly fetchImpl;
+    constructor(options: JwksVerifierOptions);
+    verify(token: string): Promise<BastionJwtPayload>;
+    /** Single-flight: concurrent verifies during a refetch share one HTTP call. */
+    private fetchKeys;
+    private ensureFresh;
+    private refetchForUnknownKid;
+}

package/dist/cjs/core/jwks-verifier.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwksVerifier = void 0;
+const jose_1 = require("jose");
+const errors_js_1 = require("./errors.js");
+const types_js_1 = require("./types.js");
+/**
+ * Refetch cooldown when a token names a `kid` we do not have. The kid comes
+ * from an unverified header, so it is attacker-controlled: without a
+ * cooldown a flood of random kids becomes a request amplifier against
+ * Bastion's JWKS route.
+ */
+const UNKNOWN_KID_REFETCH_COOLDOWN_MS = 30_000;
+/**
+ * The canonical consumer of Bastion's JWKS (docs/BASTION_INTEGRATION.md):
+ * keys cached and indexed by `kid`, refetch on an unknown kid with a
+ * cooldown, stale cache served when a refetch fails. Second safety net only:
+ * Bastion publishes a key before signing with it (publish-before-use), so a
+ * correctly configured consumer should never meet an unknown kid.
+ */
+class JwksVerifier {
+    keys = new Map();
+    fetchedAt = 0;
+    lastUnknownKidRefetchAt = 0;
+    inFlight = null;
+    jwksUrl;
+    ttlMs;
+    issuer;
+    logger;
+    fetchImpl;
+    constructor(options) {
+        this.jwksUrl = `${options.baseUrl.replace(/\/$/, '')}/.well-known/jwks.json`;
+        this.ttlMs = options.ttlMs ?? 300_000;
+        this.issuer = options.issuer === undefined ? 'bastion' : options.issuer;
+        this.logger = options.logger ?? types_js_1.silentLogger;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async verify(token) {
+        let kid;
+        try {
+            ({ kid } = (0, jose_1.decodeProtectedHeader)(token));
+        }
+        catch {
+            throw new errors_js_1.BastionTokenError('malformed', 'Malformed token');
+        }
+        if (!kid)
+            throw new errors_js_1.BastionTokenError('missing_kid', 'Missing kid in JWT header');
+        await this.ensureFresh();
+        let key = this.keys.get(kid);
+        if (!key) {
+            await this.refetchForUnknownKid();
+            key = this.keys.get(kid);
+        }
+        if (!key) {
+            this.logger.warn(`JWT verification failed: unknown kid=${kid}`);
+            throw new errors_js_1.BastionTokenError('unknown_kid', 'Unknown or expired kid');
+        }
+        try {
+            const { payload } = await (0, jose_1.jwtVerify)(token, key, {
+                algorithms: ['RS256'],
+                ...(this.issuer ? { issuer: this.issuer } : {}),
+            });
+            return payload;
+        }
+        catch {
+            throw new errors_js_1.BastionTokenError('invalid', 'Invalid token');
+        }
+    }
+    /** Single-flight: concurrent verifies during a refetch share one HTTP call. */
+    fetchKeys() {
+        this.inFlight ??= (async () => {
+            try {
+                const res = await this.fetchImpl(this.jwksUrl);
+                if (!res.ok)
+                    throw new Error(`JWKS fetch failed: ${res.status}`);
+                const { keys } = (await res.json());
+                const next = new Map();
+                for (const jwk of keys) {
+                    if (!jwk.kid)
+                        continue;
+                    next.set(jwk.kid, await (0, jose_1.importJWK)(jwk, 'RS256'));
+                }
+                this.keys = next;
+                this.fetchedAt = Date.now();
+            }
+            finally {
+                this.inFlight = null;
+            }
+        })();
+        return this.inFlight;
+    }
+    async ensureFresh() {
+        const stale = Date.now() - this.fetchedAt >= this.ttlMs;
+        if (!stale && this.keys.size)
+            return;
+        try {
+            await this.fetchKeys();
+        }
+        catch (err) {
+            if (!this.keys.size)
+                throw err;
+            this.logger.warn(`JWKS fetch failed, serving stale cache: ${err.message}`);
+        }
+    }
+    async refetchForUnknownKid() {
+        const now = Date.now();
+        if (now - this.lastUnknownKidRefetchAt < UNKNOWN_KID_REFETCH_COOLDOWN_MS)
+            return;
+        this.lastUnknownKidRefetchAt = now;
+        try {
+            await this.fetchKeys();
+        }
+        catch (err) {
+            this.logger.warn(`JWKS refetch for unknown kid failed: ${err.message}`);
+        }
+    }
+}
+exports.JwksVerifier = JwksVerifier;

package/dist/cjs/core/service-token-provider.d.ts

@@ -0,0 +1,21 @@
+import type { BastionHttp, ClientAuthInput } from './bastion-http.js';
+import { type BastionLogger } from './types.js';
+/**
+ * Holds the service-client token for outbound calls and renews it ahead of
+ * `exp`. Single-flight: a burst of first calls shares one `POST /auth/client`
+ * instead of issuing one per caller — the previous per-service copies had no
+ * such guard.
+ */
+export declare class ServiceTokenProvider {
+    private readonly http;
+    private readonly credentials;
+    private readonly logger;
+    private token;
+    private expiresAt;
+    private inFlight;
+    /** Tenant the token was issued for — the tenant `POST /events` rows land in. */
+    tenantId: string | null;
+    constructor(http: BastionHttp, credentials: ClientAuthInput, logger?: BastionLogger);
+    getToken(): Promise<string>;
+    private refresh;
+}

package/dist/cjs/core/service-token-provider.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTokenProvider = void 0;
+const jose_1 = require("jose");
+const types_js_1 = require("./types.js");
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+const FALLBACK_TTL_MS = 60 * 60 * 1000;
+/**
+ * Holds the service-client token for outbound calls and renews it ahead of
+ * `exp`. Single-flight: a burst of first calls shares one `POST /auth/client`
+ * instead of issuing one per caller — the previous per-service copies had no
+ * such guard.
+ */
+class ServiceTokenProvider {
+    http;
+    credentials;
+    logger;
+    token = null;
+    expiresAt = 0;
+    inFlight = null;
+    /** Tenant the token was issued for — the tenant `POST /events` rows land in. */
+    tenantId = null;
+    constructor(http, credentials, logger = types_js_1.silentLogger) {
+        this.http = http;
+        this.credentials = credentials;
+        this.logger = logger;
+    }
+    getToken() {
+        if (this.token && Date.now() < this.expiresAt - REFRESH_MARGIN_MS) {
+            return Promise.resolve(this.token);
+        }
+        this.inFlight ??= this.refresh().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async refresh() {
+        const { accessToken } = await this.http.clientAuth(this.credentials);
+        const { exp, tenantId } = (0, jose_1.decodeJwt)(accessToken);
+        this.token = accessToken;
+        this.expiresAt = exp ? exp * 1000 : Date.now() + FALLBACK_TTL_MS;
+        this.tenantId = tenantId ?? null;
+        this.logger.log('service client token refreshed');
+        return accessToken;
+    }
+}
+exports.ServiceTokenProvider = ServiceTokenProvider;

package/dist/cjs/core/types.d.ts

@@ -0,0 +1,48 @@
+/** Claims Bastion puts on every RS256 token it signs (see bastion/CLAUDE.md, "JWT payload"). */
+interface CommonClaims {
+    sub: string;
+    tenantId: string;
+    tenantSlug: string;
+    iss?: string;
+    aud?: string;
+    jti?: string;
+    iat: number;
+    exp: number;
+}
+/** A user session token: `POST /auth/login`, `/auth/refresh`, `/auth/exchange`. Never carries `type`. */
+export interface UserJwtPayload extends CommonClaims {
+    type?: undefined;
+    email: string | null;
+    username: string | null;
+    image: string | null;
+    preferredLocale: string | null;
+    appSlug: string;
+    role: string;
+    permissions: string[];
+    sessionId?: string;
+}
+/** A machine token from `POST /auth/client`. Discriminated by `type`. */
+export interface ServiceClientJwtPayload extends CommonClaims {
+    type: 'service_client';
+    clientName: string;
+    serviceSlug: string;
+    scopes: string[];
+}
+export type BastionJwtPayload = UserJwtPayload | ServiceClientJwtPayload;
+export declare function isServiceClientToken(payload: BastionJwtPayload): payload is ServiceClientJwtPayload;
+export interface TokenResponse {
+    accessToken: string;
+}
+export interface AuditEventInput {
+    event: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Minimal logger so the core never depends on a framework. Defaults to silent. */
+export interface BastionLogger {
+    warn(message: string): void;
+    error(message: string): void;
+    log(message: string): void;
+}
+export declare const silentLogger: BastionLogger;
+export {};

package/dist/cjs/core/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLogger = void 0;
+exports.isServiceClientToken = isServiceClientToken;
+function isServiceClientToken(payload) {
+    return payload.type === 'service_client';
+}
+exports.silentLogger = {
+    warn: () => undefined,
+    error: () => undefined,
+    log: () => undefined,
+};

package/dist/cjs/nest/bastion-audit.service.d.ts

@@ -0,0 +1,29 @@
+import { OnModuleInit } from '@nestjs/common';
+import type { UserJwtPayload } from '../core/types.js';
+import { BastionService } from './bastion.service.js';
+import { type BastionModuleOptions } from './options.js';
+/**
+ * Fire-and-forget audit writes to `POST /events` under this service's own
+ * machine token. Never throws: a failed write is logged, the request that
+ * produced it is not affected.
+ */
+export declare class BastionAuditService implements OnModuleInit {
+    private readonly bastion;
+    private readonly logger;
+    private readonly tokens;
+    private tenantMismatchWarned;
+    constructor(bastion: BastionService, options: BastionModuleOptions);
+    onModuleInit(): Promise<void>;
+    /** Tenant of this service's machine token, once known. */
+    get tenantId(): string | null;
+    write(event: string, opts?: {
+        userId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Attribute an event to an admin user. `userId` is only set when the actor
+     * belongs to the same tenant as this service's token — Bastion rejects a
+     * foreign userId silently — otherwise the actor goes into `metadata`.
+     */
+    writeAsAdmin(event: string, actor: UserJwtPayload | undefined, metadata?: Record<string, unknown>): Promise<void>;
+}

package/dist/cjs/nest/bastion-audit.service.js

@@ -0,0 +1,97 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var BastionAuditService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BastionAuditService = void 0;
+const common_1 = require("@nestjs/common");
+const service_token_provider_js_1 = require("../core/service-token-provider.js");
+const bastion_service_js_1 = require("./bastion.service.js");
+const options_js_1 = require("./options.js");
+const nest_logger_js_1 = require("./nest-logger.js");
+/**
+ * Fire-and-forget audit writes to `POST /events` under this service's own
+ * machine token. Never throws: a failed write is logged, the request that
+ * produced it is not affected.
+ */
+let BastionAuditService = BastionAuditService_1 = class BastionAuditService {
+    bastion;
+    logger = new common_1.Logger(BastionAuditService_1.name);
+    tokens;
+    tenantMismatchWarned = false;
+    constructor(bastion, options) {
+        this.bastion = bastion;
+        this.tokens = options.apiKey
+            ? new service_token_provider_js_1.ServiceTokenProvider(bastion.http, {
+                apiKey: options.apiKey,
+                serviceSlug: options.serviceSlug,
+                ...(options.tenantSlug ? { tenantSlug: options.tenantSlug } : {}),
+            }, (0, nest_logger_js_1.nestLogger)(BastionAuditService_1.name))
+            : null;
+    }
+    async onModuleInit() {
+        if (!this.tokens)
+            return;
+        await this.tokens.getToken().catch((err) => this.logger.error(`Bastion unreachable at startup, will retry on first write: ${err.message}`));
+    }
+    /** Tenant of this service's machine token, once known. */
+    get tenantId() {
+        return this.tokens?.tenantId ?? null;
+    }
+    async write(event, opts = {}) {
+        if (!this.tokens) {
+            this.logger.warn(`audit write skipped, no apiKey configured event=${event}`);
+            return;
+        }
+        let token;
+        try {
+            token = await this.tokens.getToken();
+        }
+        catch (err) {
+            this.logger.error(`audit write skipped, no service client token event=${event}: ${err.message}`);
+            return;
+        }
+        await this.bastion
+            .writeAuditEvent(token, { event, ...opts })
+            .catch((err) => this.logger.error(`audit write failed event=${event}: ${err.message}`));
+    }
+    /**
+     * Attribute an event to an admin user. `userId` is only set when the actor
+     * belongs to the same tenant as this service's token — Bastion rejects a
+     * foreign userId silently — otherwise the actor goes into `metadata`.
+     */
+    async writeAsAdmin(event, actor, metadata = {}) {
+        await this.tokens?.getToken().catch(() => undefined);
+        const sameTenant = Boolean(actor?.sub) && Boolean(this.tenantId) && actor?.tenantId === this.tenantId;
+        if (sameTenant && actor)
+            return this.write(event, { userId: actor.sub, metadata });
+        if (actor && !this.tenantMismatchWarned) {
+            this.tenantMismatchWarned = true;
+            this.logger.warn(`admin tenant (${actor.tenantSlug ?? actor.tenantId}) differs from this service's tenant (${this.tenantId ?? 'unknown'}) — audit events fall back to actor metadata instead of userId`);
+        }
+        return this.write(event, {
+            metadata: {
+                ...metadata,
+                actorId: actor?.sub ?? 'unknown',
+                actorRole: actor?.role ?? 'unknown',
+                actorAppSlug: actor?.appSlug ?? 'unknown',
+            },
+        });
+    }
+};
+exports.BastionAuditService = BastionAuditService;
+exports.BastionAuditService = BastionAuditService = BastionAuditService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(options_js_1.BASTION_OPTIONS)),
+    __metadata("design:paramtypes", [bastion_service_js_1.BastionService, Object])
+], BastionAuditService);

package/dist/cjs/nest/bastion-jwks.service.d.ts

@@ -0,0 +1,8 @@
+import type { BastionJwtPayload } from '../core/types.js';
+import { type BastionModuleOptions } from './options.js';
+/** Verifies inbound Bastion tokens against the cached JWKS. Throws `UnauthorizedException` on any failure. */
+export declare class BastionJwksService {
+    private readonly verifier;
+    constructor(options: BastionModuleOptions);
+    verify(token: string): Promise<BastionJwtPayload>;
+}