@deplois/api 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+# @deplois/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NestJS 11 공통 API 모듈. 사용자와 세션을 관리하며 실제 로그인 인증 및 OAuth는 외부 모듈에서 처리합니다. Node.js 22 이상을 사용합니다.
+
+## 구성
+
+- `APIModule`: 응답 포맷, DTO Body 검증, 예외 처리, 요청 로그.
+- `SessionModule`: 선택적으로 등록하는 `/session` API.
+- `IdentityService`: `userPlugin`, `sessionPlugin` 접근.
+- `SessionGuard`: 유효한 세션을 확인하고 `request.session`에 저장.
+- `UserGuard`: 세션 검증 후 활성 사용자가 최소 1명인지 확인하고 `request.users`에 저장.
+- `@deplois/api/database`: `UserEntity`, `SessionEntity`, `TypeORMIdentityStore`, `createDatabaseClient`, `mergeMetadata`.
+
+별도 AccessToken은 사용하지 않습니다. 세션 하나에 여러 사용자 ID를 연결할 수 있습니다. 실제 사용자 정보는 사용자 테이블에서 조회하므로 세션 metadata에 개인정보를 복제하지 않습니다.
+
+## DB 연결
+
+기존 Nest 앱에 패키지와 필요한 peer dependency를 설치합니다. PostgreSQL 저장소를 쓸 경우 `typeorm`, `pg`도 설치합니다. 현재 TypeORM 지원 버전은 `^1.1.0`입니다.
+
+```typescript
+import { Module } from '@nestjs/common'
+import { APIModule, SessionModule, createIdentityPlugins } from '@deplois/api'
+import { createDatabaseClient, TypeORMIdentityStore, UserEntity, SessionEntity } from '@deplois/api/database'
+
+export const databaseClient = createDatabaseClient({
+    type: 'postgres',
+    url: process.env.DATABASE_URL,
+    entities: [UserEntity, SessionEntity],
+    synchronize: false
+})
+
+@Module({
+    imports: [
+        APIModule.forRootAsync({
+            useFactory: async () => ({
+                identity: createIdentityPlugins(new TypeORMIdentityStore(await databaseClient.connect()), {
+                    sessionDuration: 60 * 60 * 24
+                })
+            })
+        }),
+        SessionModule
+    ]
+})
+export class AppModule {}
+```
+
+기존 DataSource를 `new TypeORMIdentityStore(dataSource)`에 직접 전달해도 됩니다. DataSource의 entities에는 두 Entity를 모두 등록합니다. 테이블 이름은 `api_user`, `api_session`, `api_session_users`입니다. 스키마 생성/변경은 앱의 TypeORM migration으로 적용하세요. 모듈은 기존 DB에 자동으로 synchronize하지 않습니다.
+
+`databaseClient.get()`으로 연결된 DataSource와 repository/manager를 사용할 수 있습니다. 앱 종료 시 `databaseClient.disconnect()`를 호출하세요. Repository를 직접 수정하면 플러그인의 metadata 병합·비활성화 규칙은 적용되지 않습니다.
+
+## 사용자 등록 및 세션 로그인
+
+```typescript
+constructor(private readonly identity: IdentityService) {}
+
+// 서버에서 확인한 사용자 정보로 등록
+const userResult = await this.identity.userPlugin.create({
+    profile: { fullName: '민재', emailAddress: 'minjae@example.com' },
+    metadata: {}
+})
+if (!userResult.success) throw userResult.error
+
+// 별도 인증 모듈에서 로그인 검증을 마친 뒤 실행
+const result = await this.identity.sessionPlugin.addUser(sessionToken, userResult.data.id)
+if (!result.success) throw result.error
+
+return { token: result.data.token }
+```
+
+`addUser`는 로그인 시 세션 토큰을 교체합니다. 응답의 새 토큰을 클라이언트에 저장해야 하며 이전 토큰은 더 이상 사용할 수 없습니다. 클라이언트가 보낸 userId만으로 호출하는 공개 로그인 API를 만들지 마세요. 인증된 userId를 별도 OAuth 모듈에서 전달합니다.
+
+- `userPlugin.create({ profile?, metadata? })`
+- `userPlugin.get(userId)`
+- `userPlugin.update(userId, { profile?, metadata? })`
+- `userPlugin.disable(userId)`: `is_active=false`, `deleted_date` 설정, 이후 로그인 사용자에서 제외.
+- `sessionPlugin.create({ userId?, metadata? })`: 익명 또는 인증 완료된 사용자 세션 생성.
+- `sessionPlugin.get(token)`: 검증 및 자동 만료 연장. 이미 만료된 세션은 연장하지 않음.
+- `sessionPlugin.addUser(token, userId)`: 사용자 연결 및 토큰 교체.
+- `sessionPlugin.removeUser(token, userId)`: 해당 계정만 로그아웃.
+- `sessionPlugin.revoke(token)`: 세션 전체 폐기.
+
+플러그인 결과는 `{ success: true, data }` 또는 `{ success: false, error }`입니다. 토큰은 128자 base64url 난수이며 DB에는 SHA-256 해시만 저장합니다.
+
+`UserGuard`는 복수 사용자 목록을 제공합니다. 특정 사용자 작업에서는 대상 userId가 `request.users`에 속하는지 추가로 확인해야 합니다. 첫 번째 사용자를 임의로 현재 사용자로 취급하지 않습니다.
+
+## 세션 API
+
+`SessionModule`을 import한 경우에만 생성됩니다. 앱의 global prefix가 있으면 그대로 적용됩니다.
+
+| 메서드 | 경로 | data |
+| --- | --- | --- |
+| PUT | `/session` | `{ id, token, expires_in }` (201) |
+| GET | `/session` | `{ expires_in }` |
+| GET | `/session/users` | `{ users: [{ id, profile, created_at }] }` |
+| DELETE | `/session/user/:userId` | `null` |
+| DELETE | `/session` | `null` |
+
+PUT 외 요청에는 `Authorization: Bearer <session token>`을 전달합니다. `profile` 응답은 `full_name`, `email_address`, `phone_number`, `image_url`입니다. 기존 API의 사용자 응답 전체를 그대로 복제한 것은 아닙니다.
+
+## 응답 및 오류
+
+```typescript
+{ success: true, data: {}, error: null }
+{ success: false, data: null, error: { code: 'WRONG_PARAMETER', message: 'Invalid parameter.' } }
+```
+
+Body DTO는 class-validator로 검증합니다. 필수 필드 누락은 `A required parameter is missing.`, 잘못된 값/미등록 필드는 `Invalid parameter.`입니다. Query/Param 검증은 각 컨트롤러의 pipe로 지정합니다.
+
+```typescript
+throw errorPlugin.createException('WRONG_SESSION', 'Wrong session.', 400, { cause: originalError })
+```
+
+cause는 응답에 노출되지 않습니다. `APIModule`의 `onError(error, context)`에서 서버 오류 추적 시스템으로 전달할 수 있습니다. 알 수 없는 오류 내용도 기본적으로 숨깁니다.
+
+`@RawResponse()`는 성공 응답의 래핑만 해제합니다. OAuth 표준 오류 응답이 필요한 컨트롤러는 별도 예외 필터를 사용하세요.
+
+## 로그 및 metadata
+
+요청 로그는 기본적으로 경로·상태·시간만 기록하며 헤더/쿼리/본문을 기록하지 않습니다. `logging: false`로 끄거나 `logging: { bodies: true, write: entry => ... }`로 설정합니다. 본문을 켜면 자격증명 관련 키는 필터링합니다. 필터만 믿고 민감한 본문을 기록하지 마세요.
+
+`userPlugin.update`의 metadata/profile은 기존 키를 유지하고 전달한 키만 병합합니다. `undefined`는 해당 키 삭제, `null`은 null 저장, 배열은 교체입니다. 세션 사용자 연결과 만료/폐기 변경은 TypeORM transaction에서 처리합니다.
+
+`IdentityStore` 인터페이스를 구현하면 다른 저장소도 쓸 수 있습니다. 세션 update는 현재 토큰 해시와 만료/폐기 상태를 원자적으로 확인해야 합니다.
+
+## 개발
+
+```sh
+npm run check
+npm test
+npm pack
+```
+
+테스트는 메모리 저장소를 이용한 Nest HTTP 통합 테스트와 세션 수명주기 테스트입니다. 실제 PostgreSQL 연결/동시성 테스트는 별도로 수행해야 합니다. 패키지는 아직 게시하지 않았습니다.
+
+## 파일 로그와 CLI
+
+```typescript
+import { createAPI } from '@deplois/api'
+import { AppModule } from './app.module'
+
+async function bootstrap() {
+    const api = await createAPI(AppModule, {
+        port: 4000,
+        host: '127.0.0.1',
+        name: 'deplois API',
+        logs: { directory: 'logs', maxFileSize: 10 * 1024 * 1024, retentionDays: 30 }
+    })
+    api.app.setGlobalPrefix('v1')
+    await api.listen()
+}
+
+void bootstrap().catch(() => { process.exitCode = 1 })
+```
+
+`APIModule`과 함께 사용하면 Nest 로그·HTTP 요청 로그·처리된 요청 오류를 콘솔 대신 `logs/api-<pid>-YYYY-MM-DD-<part>.jsonl`에 기록합니다. 날짜는 UTC 기준입니다. 각 행은 JSON이고, 용량 기준으로 분할됩니다. 보관 기간 정리는 시작 후 첫 기록과 날짜 변경 시 해당 이름의 로그 파일에만 적용합니다. `logs/`는 Git에서 제외하세요.
+
+TTY에서는 요청 수, 최근 1,000건의 응답 시간 중앙값, 오류/경고 로그 수, 실행 시간과 주소를 표시합니다. `s` 요약, `l` 최근 로그, `n` 최근 요청, `r` 통계 초기화, `?` 도움말, `q` 정상 종료입니다. `r`은 서버 재시작이 아닙니다. 로그/요청 보기는 최근 기록 일부이며 전체 기록은 파일에 있습니다.
+
+`cli: false` 또는 터미널이 없는 환경에서는 CLI를 표시하지 않습니다. SIGINT/SIGTERM 및 `api.close()`는 Nest 종료 훅을 실행하고 대기 중인 파일 기록을 마칩니다. DB 정리는 앱의 종료 훅에서 처리하세요. `console.log`나 별도 라이브러리의 stdout 출력은 가로채지 않습니다. Nest `Logger` 또는 `api.logger`를 사용하세요.
+
+기본 본문 기록 정책은 그대로 유지합니다. `APIModule`에 `logging: { bodies: true }`를 설정해야 본문도 기록합니다. 사용자 지정 `logging.write`는 기본 HTTP logger를 대체하므로 파일 기록/CLI 요청 통계도 직접 연결해야 합니다. 문자열로 출력한 비밀번호나 오류 메시지 속 비밀 값까지 자동 판별하지는 않습니다.
+
+디스크 기록 실패/쓰기 대기열 초과는 `failedWrites`와 CLI에 표시합니다. 대기열은 메모리 보호를 위해 최대 10,000건으로 제한하며 초과 로그는 버립니다. 비대화형 환경의 모니터링에서는 `api.logger.failedWrites`를 확인할 수 있습니다.
+
+
+## 로컬 배포 스크립트
+
+```sh
+npm run publish -- fetch "수정 내용" --deploy
+npm run publish -- minor "기능 추가" --deploy
+npm run publish -- major "호환성 변경" --deploy
+npm run publish -- 1.2.3 "릴리스 내용" --deploy
+```
+
+`fetch`는 세 번째 버전을 1 올립니다. minor/major를 올리면 하위 버전은 0으로 초기화합니다. 테스트·빌드 후 버전을 변경하고 변경 파일 전체를 commit → push → npmjs 공개 배포합니다. `--deploy`를 빼면 commit·push까지만 진행합니다. `npm run deploy`는 현재 버전을 테스트·빌드해서 npm에만 배포합니다.
+
+각 패키지 폴더에 별도 Git 저장소와 origin이 설정되어 있어야 합니다. 상위 저장소를 대신 commit하지 않습니다. npm 배포 시에는 npmjs 로그인 및 배포 권한이 필요합니다. 스크립트 자체는 template과 동일하게 Git 및 npm 패키지에서 제외하는 로컬 파일입니다.

package/dist/api.module.d.ts

@@ -0,0 +1,10 @@
+import { DynamicModule, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { APIAsyncOptions, APIOptions } from './options';
+import { RequestLogger } from './system/logger/request.logger';
+export declare class APIModule implements NestModule {
+    private readonly logger;
+    static forRoot(options?: APIOptions): DynamicModule;
+    static forRootAsync(options: APIAsyncOptions): DynamicModule;
+    constructor(logger: RequestLogger);
+    configure(consumer: MiddlewareConsumer): void;
+}

package/dist/api.module.js

@@ -0,0 +1,58 @@
+"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 APIModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const options_1 = require("./options");
+const http_exception_filter_1 = require("./system/filter/http-exception.filter");
+const response_interceptor_1 = require("./system/interceptor/response.interceptor");
+const body_validation_pipe_1 = require("./system/pipe/body-validation.pipe");
+const request_logger_1 = require("./system/logger/request.logger");
+const identity_service_1 = require("./identity/identity.service");
+const user_guard_1 = require("./system/guard/user.guard");
+const session_guard_1 = require("./system/guard/session.guard");
+let APIModule = APIModule_1 = class APIModule {
+    logger;
+    static forRoot(options = {}) {
+        return this.forRootAsync({ useFactory: () => options });
+    }
+    static forRootAsync(options) {
+        return {
+            module: APIModule_1,
+            global: true,
+            imports: options.imports ?? [],
+            providers: [
+                { provide: options_1.API_OPTIONS, useFactory: options.useFactory, inject: options.inject ?? [] },
+                request_logger_1.RequestLogger,
+                session_guard_1.SessionGuard,
+                user_guard_1.UserGuard,
+                identity_service_1.IdentityService,
+                { provide: core_1.APP_PIPE, useClass: body_validation_pipe_1.BodyValidationPipe },
+                { provide: core_1.APP_FILTER, useClass: http_exception_filter_1.HTTPExceptionFilter },
+                { provide: core_1.APP_INTERCEPTOR, useClass: response_interceptor_1.ResponseInterceptor }
+            ],
+            exports: [options_1.API_OPTIONS, session_guard_1.SessionGuard, user_guard_1.UserGuard, identity_service_1.IdentityService]
+        };
+    }
+    constructor(logger) {
+        this.logger = logger;
+    }
+    configure(consumer) {
+        consumer.apply(this.logger.use.bind(this.logger)).forRoutes('{*path}');
+    }
+};
+exports.APIModule = APIModule;
+exports.APIModule = APIModule = APIModule_1 = __decorate([
+    (0, common_1.Module)({}),
+    __metadata("design:paramtypes", [request_logger_1.RequestLogger])
+], APIModule);

package/dist/controller/session.controller.d.ts

@@ -0,0 +1,30 @@
+import type { Request as ExpressRequest, Response } from 'express';
+import { IdentityService } from '../identity/identity.service';
+import { SessionRequest } from '../system/guard/session.guard';
+import type { Session } from '../identity/interface';
+export declare class SessionController {
+    private readonly identity;
+    constructor(identity: IdentityService);
+    create(request: ExpressRequest, response: Response): Promise<{
+        id: string;
+        token: string;
+        expires_in: number;
+    }>;
+    get(request: SessionRequest<Session>, response: Response): {
+        expires_in: number;
+    };
+    users(request: SessionRequest<Session>, response: Response): Promise<{
+        users: {
+            id: string;
+            profile: {
+                full_name: string | null;
+                email_address: string | null;
+                phone_number: string | null;
+                image_url: string | null;
+            };
+            created_at: string;
+        }[];
+    }>;
+    removeUser(request: ExpressRequest, userId: string): Promise<null>;
+    revoke(request: ExpressRequest): Promise<null>;
+}

package/dist/controller/session.controller.js

@@ -0,0 +1,115 @@
+"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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionController = void 0;
+const common_1 = require("@nestjs/common");
+const app_exception_1 = require("../system/error/app.exception");
+const identity_service_1 = require("../identity/identity.service");
+const session_guard_1 = require("../system/guard/session.guard");
+let SessionController = class SessionController {
+    identity;
+    constructor(identity) {
+        this.identity = identity;
+    }
+    async create(request, response) {
+        const result = await this.identity.sessionPlugin.create({ metadata: { ip_address: request.ip, user_agent: request.headers['user-agent'] ?? null } });
+        if (!result.success)
+            throw result.error;
+        response.setHeader('Cache-Control', 'no-store');
+        return { id: result.data.session.id, token: result.data.token, expires_in: Math.max(0, Math.floor((result.data.session.expiresDate.getTime() - Date.now()) / 1000)) };
+    }
+    get(request, response) {
+        response.setHeader('Cache-Control', 'no-store');
+        return { expires_in: Math.max(0, Math.floor((request.session.expiresDate.getTime() - Date.now()) / 1000)) };
+    }
+    async users(request, response) {
+        response.setHeader('Cache-Control', 'no-store');
+        const results = await Promise.all(request.session.userIds.map(id => this.identity.userPlugin.get(id)));
+        for (const result of results) {
+            if (!result.success && !(result.error instanceof app_exception_1.AppException && result.error.error.code === 'USER_NOT_FOUND'))
+                throw result.error;
+        }
+        return { users: results.flatMap(result => result.success ? [{
+                    id: result.data.id,
+                    profile: {
+                        full_name: result.data.profile.fullName ?? null,
+                        email_address: result.data.profile.emailAddress ?? null,
+                        phone_number: result.data.profile.phoneNumber ?? null,
+                        image_url: result.data.profile.imageUrl ?? null
+                    },
+                    created_at: result.data.createdDate.toISOString()
+                }] : []) };
+    }
+    async removeUser(request, userId) {
+        const result = await this.identity.sessionPlugin.removeUser((0, session_guard_1.getBearerToken)(request.headers.authorization), userId);
+        if (!result.success)
+            throw result.error;
+        return null;
+    }
+    async revoke(request) {
+        const result = await this.identity.sessionPlugin.revoke((0, session_guard_1.getBearerToken)(request.headers.authorization));
+        if (!result.success)
+            throw result.error;
+        return null;
+    }
+};
+exports.SessionController = SessionController;
+__decorate([
+    (0, common_1.Put)(),
+    (0, common_1.HttpCode)(201),
+    __param(0, (0, common_1.Request)()),
+    __param(1, (0, common_1.Res)({ passthrough: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "create", null);
+__decorate([
+    (0, common_1.Get)(),
+    (0, common_1.UseGuards)(session_guard_1.SessionGuard),
+    __param(0, (0, common_1.Request)()),
+    __param(1, (0, common_1.Res)({ passthrough: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", void 0)
+], SessionController.prototype, "get", null);
+__decorate([
+    (0, common_1.Get)('users'),
+    (0, common_1.UseGuards)(session_guard_1.SessionGuard),
+    __param(0, (0, common_1.Request)()),
+    __param(1, (0, common_1.Res)({ passthrough: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "users", null);
+__decorate([
+    (0, common_1.Delete)('user/:userId'),
+    (0, common_1.UseGuards)(session_guard_1.SessionGuard),
+    __param(0, (0, common_1.Request)()),
+    __param(1, (0, common_1.Param)('userId', new common_1.ParseUUIDPipe())),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "removeUser", null);
+__decorate([
+    (0, common_1.Delete)(),
+    (0, common_1.UseGuards)(session_guard_1.SessionGuard),
+    __param(0, (0, common_1.Request)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SessionController.prototype, "revoke", null);
+exports.SessionController = SessionController = __decorate([
+    (0, common_1.Controller)('session'),
+    __metadata("design:paramtypes", [identity_service_1.IdentityService])
+], SessionController);

package/dist/create-api.d.ts

@@ -0,0 +1,16 @@
+import type { NestApplicationOptions, Type } from '@nestjs/common';
+import { FileLogger, FileLoggerOptions } from './system/logger/file.logger';
+export interface CreateAPIOptions {
+    port?: number;
+    host?: string;
+    name?: string;
+    cli?: boolean;
+    logs?: FileLoggerOptions;
+    nest?: Omit<NestApplicationOptions, 'logger' | 'abortOnError'>;
+}
+export declare function createAPI(module: Type<unknown>, options?: CreateAPIOptions): Promise<{
+    app: import("@nestjs/common").INestApplication<any>;
+    logger: FileLogger;
+    close: () => Promise<void>;
+    listen(): Promise<void>;
+}>;

package/dist/create-api.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAPI = createAPI;
+const core_1 = require("@nestjs/core");
+const node_readline_1 = require("node:readline");
+const file_logger_1 = require("./system/logger/file.logger");
+async function createAPI(module, options = {}) {
+    const logger = new file_logger_1.FileLogger(options.logs);
+    const started = Date.now();
+    let app;
+    try {
+        app = await core_1.NestFactory.create(module, { ...options.nest, logger, abortOnError: false });
+    }
+    catch (error) {
+        logger.error(error);
+        await logger.close();
+        throw error;
+    }
+    let timer;
+    let view = 'summary';
+    let screenActive = false;
+    let address = '';
+    let closing;
+    const interactive = options.cli !== false && !!process.stdout.isTTY && !!process.stdin.isTTY;
+    const wasRaw = process.stdin.isRaw;
+    const wasPaused = process.stdin.isPaused();
+    const clean = (text) => text.replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
+    const render = () => {
+        const width = Math.max(20, (process.stdout.columns || 80) - 1);
+        const rows = [
+            `${options.name ?? 'deplois API'}  ·  ${Math.floor((Date.now() - started) / 1000)}s`,
+            `Local  ${address}`,
+            `${logger.requests} requests  ·  ${logger.median}ms median (last 1000)  ·  ${logger.errors} errors  ·  ${logger.warnings} warnings`,
+            `Logs  ${logger.directory}${logger.failedWrites ? `  ·  ${logger.failedWrites} failed/dropped writes` : ''}`,
+            ''
+        ];
+        if (view === 'logs')
+            rows.push(...logger.recent.slice(-8));
+        if (view === 'network')
+            rows.push(...logger.network.slice(-8).map(entry => `${entry.request.method} ${entry.request.path}  ${entry.response.status_code}  ${entry.response.duration_ms}ms`));
+        if (view === 'help')
+            rows.push('s summary · l recent logs · n recent requests · r reset statistics · q graceful shutdown');
+        rows.push('', 's summary · l logs · n network · r reset · ? help · q quit');
+        process.stdout.write('\x1b[H\x1b[2J' + rows.slice(0, Math.max(5, (process.stdout.rows || 24) - 1)).map(row => clean(row).slice(0, width)).join('\n'));
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        closing = (async () => {
+            if (timer)
+                clearInterval(timer);
+            if (screenActive) {
+                process.stdin.off('keypress', keypress);
+                process.stdin.setRawMode(wasRaw ?? false);
+                if (wasPaused)
+                    process.stdin.pause();
+                process.stdout.write('\x1b[?25h\x1b[?1049l');
+            }
+            process.off('SIGINT', shutdown);
+            process.off('SIGTERM', shutdown);
+            try {
+                await app.close();
+            }
+            finally {
+                await logger.close();
+            }
+        })();
+        return closing;
+    };
+    const shutdown = () => { void close().catch(() => { process.exitCode = 1; }); };
+    const keypress = (text, key) => {
+        if (text === 'q' || (key.ctrl && key.name === 'c'))
+            return shutdown();
+        if (text === 'r')
+            logger.reset();
+        if (text === 'l')
+            view = 'logs';
+        if (text === 'n')
+            view = 'network';
+        if (text === 's')
+            view = 'summary';
+        if (text === '?')
+            view = 'help';
+        render();
+    };
+    return {
+        app, logger, close,
+        async listen() {
+            try {
+                await app.listen(options.port ?? 4000, options.host ?? '127.0.0.1');
+                address = await app.getUrl();
+                process.once('SIGINT', shutdown);
+                process.once('SIGTERM', shutdown);
+                if (interactive) {
+                    screenActive = true;
+                    process.stdout.write('\x1b[?1049h\x1b[?25l');
+                    (0, node_readline_1.emitKeypressEvents)(process.stdin);
+                    process.stdin.setRawMode(true);
+                    process.stdin.resume();
+                    process.stdin.on('keypress', keypress);
+                    timer = setInterval(render, 1000);
+                    timer.unref();
+                    render();
+                }
+            }
+            catch (error) {
+                logger.error(error);
+                await close();
+                throw error;
+            }
+        }
+    };
+}

package/dist/database/client.d.ts

@@ -0,0 +1,6 @@
+import { DataSource, DataSourceOptions } from 'typeorm';
+export declare function createDatabaseClient(options: DataSourceOptions): {
+    get(): DataSource;
+    connect(): Promise<DataSource>;
+    disconnect(): Promise<void>;
+};

package/dist/database/client.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDatabaseClient = createDatabaseClient;
+const typeorm_1 = require("typeorm");
+// One explicit client per application; no import-time connections or hidden global singleton.
+function createDatabaseClient(options) {
+    const database = new typeorm_1.DataSource(options);
+    let connecting = null;
+    return {
+        get() {
+            if (!database.isInitialized)
+                throw new Error('Database client is not initialized.');
+            return database;
+        },
+        async connect() {
+            if (database.isInitialized)
+                return database;
+            if (!connecting)
+                connecting = database.initialize().finally(() => { connecting = null; });
+            return connecting;
+        },
+        async disconnect() {
+            if (connecting)
+                await connecting;
+            if (database.isInitialized)
+                await database.destroy();
+        }
+    };
+}

package/dist/database/identity.store.d.ts

@@ -0,0 +1,12 @@
+import { DataSource } from 'typeorm';
+import type { IdentityStore, Session, SessionUpdate, User } from '../identity/interface';
+export declare class TypeORMIdentityStore implements IdentityStore {
+    private readonly database;
+    constructor(database: DataSource);
+    createUser(user: User): Promise<void>;
+    getUser(id: string): Promise<User | null>;
+    updateUser(id: string, patch: Pick<Partial<User>, 'profile' | 'metadata' | 'isActive'>, now: Date): Promise<User | null>;
+    createSession(session: Session): Promise<void>;
+    getSession(tokenHash: string): Promise<Session | null>;
+    updateSession(id: string, update: SessionUpdate, now: Date, tokenHash?: string): Promise<Session | null>;
+}