@idevconn/create-icore 0.1.0

package/templates/.husky/pre-commit

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+MAX_FILES=50
+DASHES="--------------------------------------------------------"
+
+echo_print() {
+  local message="$1"
+  local color="${2:-\033[0m}"
+  printf "%s\n" "$DASHES"
+  printf "%b\n" "${color}${message}\033[0m"
+  printf "%s\n" "$DASHES"
+}
+
+check_command() {
+  local command="$1"
+  local success_message="$2"
+  local failure_message="$3"
+
+  if eval "$command"; then
+    echo_print "✅ $success_message" "\033[32m"
+  else
+    echo_print "❌ $failure_message" "\033[31m"
+    exit 1
+  fi
+}
+
+FILES_CHANGED=$(git diff --cached --name-only | wc -l)
+NON_MD_FILES=$(git diff --cached --name-only | grep -vi '\.md$' | wc -l)
+
+if [ "$FILES_CHANGED" -gt 0 ] && [ "$NON_MD_FILES" -eq 0 ]; then
+  echo_print "📝 Only Markdown files staged. Skipping lint-staged + nx checks." "\033[34m"
+  exit 0
+fi
+
+if [ "$FILES_CHANGED" -gt "$MAX_FILES" ]; then
+  echo "$DASHES"
+  echo "🔹 Max files per commit: $MAX_FILES"
+  echo "❌ You are trying to commit more than $MAX_FILES files."
+  echo "$DASHES"
+  exit 1
+fi
+
+echo_print "✅ Files staged: $FILES_CHANGED" "\033[32m"
+
+check_command "yarn lint-staged --concurrent false --relative" \
+  "lint-staged passed." \
+  "lint-staged failed. Fix the issues before committing."
+
+if [ -d libs ] || [ -d apps ]; then
+  check_command "yarn nx affected -t lint" \
+    "nx affected lint passed." \
+    "nx affected lint failed."
+  check_command "yarn nx affected -t test" \
+    "nx affected tests passed." \
+    "nx affected tests failed."
+fi

package/templates/.nvmrc

@@ -0,0 +1 @@
+22

package/templates/.prettierignore

@@ -0,0 +1,7 @@
+node_modules
+.yarn
+.pnp.*
+dist
+.nx
+coverage
+yarn.lock

package/templates/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "arrowParens": "always"
+}

package/templates/.yarnrc.yml

@@ -0,0 +1,7 @@
+enableGlobalCache: true
+
+enableScripts: true
+
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.5.0.cjs

package/templates/apps/api/.env.example

@@ -0,0 +1,19 @@
+API_ORIGIN=http://localhost
+API_PORT=3001
+
+# Auth MS transport — must match apps/microservices/auth/.env
+AUTH_TRANSPORT=tcp
+AUTH_HOST=127.0.0.1
+AUTH_PORT=4001
+# AUTH_REDIS_URL=redis://localhost:6379
+# AUTH_NATS_URL=nats://localhost:4222
+
+# Upload MS transport — must match apps/microservices/upload/.env
+UPLOAD_TRANSPORT=tcp
+UPLOAD_HOST=127.0.0.1
+UPLOAD_PORT=4002
+# UPLOAD_REDIS_URL=redis://localhost:6379
+# UPLOAD_NATS_URL=nats://localhost:4222
+
+# Per-request multipart file size cap (KB). Default 5120 (5 MB) when unset.
+MAX_FILE_SIZE_KB=5120

package/templates/apps/api/eslint.config.mjs

@@ -0,0 +1,23 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}',
+            '{projectRoot}/vitest.config.{js,ts,mjs,mts}',
+            '{projectRoot}/webpack.config.{js,ts}',
+          ],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/templates/apps/api/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "api",
+  "version": "0.0.1",
+  "private": true,
+  "devDependencies": {
+    "@types/multer": "*"
+  },
+  "dependencies": {
+    "@icore/auth-client": "*",
+    "@icore/shared": "*",
+    "@icore/upload-client": "*",
+    "@nestjs/common": "^11.1.24",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.1.24",
+    "@nestjs/platform-express": "^11.1.24",
+    "@nestjs/swagger": "^11.4.4",
+    "@nestjs/throttler": "^6.5.0",
+    "express": "^4.22.2"
+  }
+}

package/templates/apps/api/project.json

@@ -0,0 +1,76 @@
+{
+  "name": "api",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/api/src",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "webpack-cli build",
+        "args": ["--node-env=production"],
+        "cwd": "apps/api"
+      },
+      "configurations": {
+        "development": {
+          "args": ["--node-env=development"]
+        }
+      }
+    },
+    "prune-lockfile": {
+      "dependsOn": ["build"],
+      "cache": true,
+      "executor": "@nx/js:prune-lockfile",
+      "outputs": [
+        "{workspaceRoot}/dist/apps/api/package.json",
+        "{workspaceRoot}/dist/apps/api/yarn.lock"
+      ],
+      "options": {
+        "buildTarget": "build"
+      }
+    },
+    "copy-workspace-modules": {
+      "dependsOn": ["build"],
+      "cache": true,
+      "outputs": ["{workspaceRoot}/dist/apps/api/workspace_modules"],
+      "executor": "@nx/js:copy-workspace-modules",
+      "options": {
+        "buildTarget": "build"
+      }
+    },
+    "prune": {
+      "dependsOn": ["prune-lockfile", "copy-workspace-modules"],
+      "executor": "nx:noop"
+    },
+    "test": {
+      "executor": "@nx/vitest:test",
+      "outputs": ["{workspaceRoot}/coverage/apps/api"],
+      "options": {
+        "config": "apps/api/vitest.config.mts"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"]
+    },
+    "serve": {
+      "continuous": true,
+      "executor": "@nx/js:node",
+      "defaultConfiguration": "development",
+      "dependsOn": ["build"],
+      "options": {
+        "buildTarget": "api:build",
+        "runBuildTargetDependencies": false
+      },
+      "configurations": {
+        "development": {
+          "buildTarget": "api:build:development"
+        },
+        "production": {
+          "buildTarget": "api:build:production"
+        }
+      }
+    }
+  },
+  "tags": []
+}

package/templates/apps/api/src/app/abilities/__tests__/ability.guard.unit.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Reflector } from '@nestjs/core';
+import { ForbiddenException, type ExecutionContext } from '@nestjs/common';
+import { AbilityFactory } from '../ability.factory';
+import { AbilityGuard } from '../ability.guard';
+
+function ctx(user: { uid: string; role?: string } | undefined): ExecutionContext {
+  return {
+    getHandler: () => undefined,
+    getClass: () => undefined,
+    switchToHttp: () => ({ getRequest: () => ({ user }) }),
+  } as unknown as ExecutionContext;
+}
+
+describe('AbilityGuard', () => {
+  const factory = new AbilityFactory();
+
+  it('passes when no @CheckAbility metadata is present', () => {
+    const reflector = {
+      getAllAndOverride: vi.fn().mockReturnValue(undefined),
+    } as unknown as Reflector;
+    const guard = new AbilityGuard(reflector, factory);
+    expect(guard.canActivate(ctx({ uid: 'u', role: 'user' }))).toBe(true);
+  });
+
+  it('admin passes manage/all', () => {
+    const reflector = {
+      getAllAndOverride: vi.fn().mockReturnValue({ action: 'manage', subject: 'all' }),
+    } as unknown as Reflector;
+    const guard = new AbilityGuard(reflector, factory);
+    expect(guard.canActivate(ctx({ uid: 'u', role: 'admin' }))).toBe(true);
+  });
+
+  it('regular user is denied manage/all', () => {
+    const reflector = {
+      getAllAndOverride: vi.fn().mockReturnValue({ action: 'manage', subject: 'all' }),
+    } as unknown as Reflector;
+    const guard = new AbilityGuard(reflector, factory);
+    expect(() => guard.canActivate(ctx({ uid: 'u', role: 'user' }))).toThrow(ForbiddenException);
+  });
+
+  it('anonymous (no req.user) is denied manage/all', () => {
+    const reflector = {
+      getAllAndOverride: vi.fn().mockReturnValue({ action: 'manage', subject: 'all' }),
+    } as unknown as Reflector;
+    const guard = new AbilityGuard(reflector, factory);
+    expect(() => guard.canActivate(ctx(undefined))).toThrow(ForbiddenException);
+  });
+});

package/templates/apps/api/src/app/abilities/abilities.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { AbilityFactory } from './ability.factory';
+import { AbilityGuard } from './ability.guard';
+
+@Module({
+  providers: [AbilityFactory, { provide: APP_GUARD, useClass: AbilityGuard }],
+  exports: [AbilityFactory],
+})
+export class AbilitiesModule {}

package/templates/apps/api/src/app/abilities/ability.factory.ts

@@ -0,0 +1,13 @@
+import { Injectable } from '@nestjs/common';
+import { defineAbilitiesFor, type AppAbility, type VerifiedToken } from '@icore/shared';
+
+@Injectable()
+export class AbilityFactory {
+  forUser(token: VerifiedToken | null | undefined): AppAbility {
+    if (!token) return defineAbilitiesFor(null);
+    return defineAbilitiesFor({
+      id: token.uid,
+      role: token.role === 'admin' ? 'admin' : 'user',
+    });
+  }
+}

package/templates/apps/api/src/app/abilities/ability.guard.ts

@@ -0,0 +1,29 @@
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Request } from 'express';
+import type { VerifiedToken } from '@icore/shared';
+import { AbilityFactory } from './ability.factory';
+import { CHECK_ABILITY_KEY, type RequiredRule } from './check-ability.decorator';
+
+@Injectable()
+export class AbilityGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly factory: AbilityFactory,
+  ) {}
+
+  canActivate(ctx: ExecutionContext): boolean {
+    const required = this.reflector.getAllAndOverride<RequiredRule | undefined>(CHECK_ABILITY_KEY, [
+      ctx.getHandler(),
+      ctx.getClass(),
+    ]);
+    if (!required) return true;
+
+    const req = ctx.switchToHttp().getRequest<Request & { user?: VerifiedToken }>();
+    const ability = this.factory.forUser(req.user);
+    if (!ability.can(required.action, required.subject)) {
+      throw new ForbiddenException();
+    }
+    return true;
+  }
+}

package/templates/apps/api/src/app/abilities/check-ability.decorator.ts

@@ -0,0 +1,12 @@
+import { SetMetadata } from '@nestjs/common';
+import type { AbilityAction, AbilitySubject } from '@icore/shared';
+
+export const CHECK_ABILITY_KEY = 'checkAbility';
+
+export interface RequiredRule {
+  action: AbilityAction;
+  subject: AbilitySubject;
+}
+
+export const CheckAbility = (action: AbilityAction, subject: AbilitySubject) =>
+  SetMetadata(CHECK_ABILITY_KEY, { action, subject } satisfies RequiredRule);

package/templates/apps/api/src/app/app.module.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ThrottlerModule, seconds } from '@nestjs/throttler';
+import { AuthModule } from './auth/auth.module';
+import { ProfileModule } from './profile/profile.module';
+import { AbilitiesModule } from './abilities/abilities.module';
+import { StorageModule } from './storage/storage.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    ThrottlerModule.forRoot([{ name: 'auth-burst', ttl: seconds(60), limit: 10 }]),
+    AuthModule,
+    AbilitiesModule,
+    ProfileModule,
+    StorageModule,
+  ],
+})
+export class AppModule {}

package/templates/apps/api/src/app/auth/__tests__/auth.guard.unit.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Reflector } from '@nestjs/core';
+import { UnauthorizedException, type ExecutionContext } from '@nestjs/common';
+import { AuthGuard } from '../auth.guard';
+
+interface MockReq {
+  headers: Record<string, string | undefined>;
+  user?: unknown;
+}
+
+function ctx(headers: Record<string, string | undefined>): ExecutionContext {
+  const req: MockReq = { headers };
+  return {
+    getHandler: () => undefined,
+    getClass: () => undefined,
+    switchToHttp: () => ({ getRequest: () => req }),
+  } as unknown as ExecutionContext;
+}
+
+describe('AuthGuard', () => {
+  const makeGuard = (overrides: { isPublic?: boolean; verify?: () => Promise<unknown> } = {}) => {
+    const reflector = {
+      getAllAndOverride: vi.fn().mockReturnValue(overrides.isPublic ?? false),
+    } as unknown as Reflector;
+    const client = {
+      verify: vi
+        .fn()
+        .mockImplementation(overrides.verify ?? (() => Promise.resolve({ uid: 'u1' }))),
+    };
+    return { guard: new AuthGuard(reflector, client as never), client };
+  };
+
+  it('lets @Public routes through without checking the header', async () => {
+    const { guard } = makeGuard({ isPublic: true });
+    await expect(guard.canActivate(ctx({}))).resolves.toBe(true);
+  });
+
+  it('rejects when Authorization header is missing', async () => {
+    const { guard } = makeGuard();
+    await expect(guard.canActivate(ctx({ authorization: undefined }))).rejects.toBeInstanceOf(
+      UnauthorizedException,
+    );
+  });
+
+  it('rejects when scheme is not Bearer', async () => {
+    const { guard } = makeGuard();
+    await expect(guard.canActivate(ctx({ authorization: 'Basic abc' }))).rejects.toBeInstanceOf(
+      UnauthorizedException,
+    );
+  });
+
+  it('verifies token and attaches user on success', async () => {
+    const { guard } = makeGuard({ verify: () => Promise.resolve({ uid: 'u1', role: 'user' }) });
+    const c = ctx({ authorization: 'Bearer abc' });
+    await expect(guard.canActivate(c)).resolves.toBe(true);
+    const req = c.switchToHttp().getRequest() as MockReq;
+    expect((req.user as { uid: string }).uid).toBe('u1');
+  });
+
+  it('rejects when verify throws', async () => {
+    const { guard } = makeGuard({ verify: () => Promise.reject(new Error('bad')) });
+    await expect(guard.canActivate(ctx({ authorization: 'Bearer abc' }))).rejects.toBeInstanceOf(
+      UnauthorizedException,
+    );
+  });
+});

package/templates/apps/api/src/app/auth/auth.controller.ts

@@ -0,0 +1,62 @@
+import { Body, Controller, Post } from '@nestjs/common';
+import { Throttle, seconds } from '@nestjs/throttler';
+import { ApiBody, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { AuthClientService } from '@icore/auth-client';
+import { Public } from './public.decorator';
+
+// 10 auth-burst requests / 60s across register + login + refresh.
+// Server-side gate against credential-stuffing; gateway only.
+@ApiTags('auth')
+@Controller('auth')
+@Throttle({ 'auth-burst': { limit: 10, ttl: seconds(60) } })
+export class AuthController {
+  constructor(private readonly authClient: AuthClientService) {}
+
+  @Public()
+  @Post('register')
+  @ApiOperation({ summary: 'Create a new user and return an auth session' })
+  @ApiBody({
+    schema: {
+      type: 'object',
+      required: ['email', 'password'],
+      properties: {
+        email: { type: 'string', format: 'email' },
+        password: { type: 'string', minLength: 8 },
+      },
+    },
+  })
+  register(@Body() body: { email: string; password: string }) {
+    return this.authClient.signup(body.email, body.password);
+  }
+
+  @Public()
+  @Post('login')
+  @ApiOperation({ summary: 'Exchange email + password for an auth session' })
+  @ApiBody({
+    schema: {
+      type: 'object',
+      required: ['email', 'password'],
+      properties: {
+        email: { type: 'string', format: 'email' },
+        password: { type: 'string' },
+      },
+    },
+  })
+  login(@Body() body: { email: string; password: string }) {
+    return this.authClient.login(body.email, body.password);
+  }
+
+  @Public()
+  @Post('refresh')
+  @ApiOperation({ summary: 'Exchange a refresh token for a fresh access token' })
+  @ApiBody({
+    schema: {
+      type: 'object',
+      required: ['refreshToken'],
+      properties: { refreshToken: { type: 'string' } },
+    },
+  })
+  refresh(@Body() body: { refreshToken: string }) {
+    return this.authClient.refresh(body.refreshToken);
+  }
+}

package/templates/apps/api/src/app/auth/auth.guard.ts

@@ -0,0 +1,42 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Inject,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthClientService } from '@icore/auth-client';
+import type { Request } from 'express';
+import { IS_PUBLIC_KEY } from './public.decorator';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    @Inject(AuthClientService) private readonly authClient: AuthClientService,
+  ) {}
+
+  async canActivate(ctx: ExecutionContext): Promise<boolean> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      ctx.getHandler(),
+      ctx.getClass(),
+    ]);
+    if (isPublic) return true;
+
+    const req = ctx.switchToHttp().getRequest<Request & { user?: unknown }>();
+    const header = req.headers.authorization ?? '';
+    const [scheme, token] = header.split(' ');
+    if (scheme !== 'Bearer' || !token) {
+      throw new UnauthorizedException('missing_bearer');
+    }
+
+    try {
+      const verified = await this.authClient.verify(token);
+      req.user = verified;
+      return true;
+    } catch {
+      throw new UnauthorizedException('invalid_token');
+    }
+  }
+}

package/templates/apps/api/src/app/auth/auth.module.ts

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { ThrottlerGuard } from '@nestjs/throttler';
+import { AuthClientModule } from '@icore/auth-client';
+import { AuthController } from './auth.controller';
+import { AuthGuard } from './auth.guard';
+
+@Module({
+  imports: [AuthClientModule.forRoot()],
+  controllers: [AuthController],
+  providers: [
+    { provide: APP_GUARD, useClass: ThrottlerGuard },
+    { provide: APP_GUARD, useClass: AuthGuard },
+  ],
+  exports: [AuthClientModule],
+})
+export class AuthModule {}

package/templates/apps/api/src/app/auth/public.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = (): MethodDecorator & ClassDecorator => SetMetadata(IS_PUBLIC_KEY, true);

package/templates/apps/api/src/app/profile/profile.controller.ts

@@ -0,0 +1,15 @@
+import { Controller, Get, Req } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import type { Request } from 'express';
+import type { VerifiedToken } from '@icore/shared';
+
+@ApiTags('profile')
+@ApiBearerAuth()
+@Controller('profile')
+export class ProfileController {
+  @Get()
+  @ApiOperation({ summary: 'Return the authenticated user (uid / email / role)' })
+  me(@Req() req: Request & { user?: VerifiedToken }): VerifiedToken | undefined {
+    return req.user;
+  }
+}

package/templates/apps/api/src/app/profile/profile.module.ts

@@ -0,0 +1,5 @@
+import { Module } from '@nestjs/common';
+import { ProfileController } from './profile.controller';
+
+@Module({ controllers: [ProfileController] })
+export class ProfileModule {}

package/templates/apps/api/src/app/storage/__tests__/assert-ownership.unit.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { ForbiddenException } from '@nestjs/common';
+import { assertOwnership } from '../assert-ownership';
+
+describe('assertOwnership', () => {
+  it('passes when the path starts with userId/', () => {
+    expect(() => assertOwnership({ bucket: 'b', path: 'user-1/foo.txt' }, 'user-1')).not.toThrow();
+  });
+
+  it('throws ForbiddenException on a foreign prefix', () => {
+    expect(() => assertOwnership({ bucket: 'b', path: 'attacker/foo.txt' }, 'user-1')).toThrow(
+      ForbiddenException,
+    );
+  });
+
+  it('throws when path has no prefix at all', () => {
+    expect(() => assertOwnership({ bucket: 'b', path: 'foo.txt' }, 'user-1')).toThrow(
+      ForbiddenException,
+    );
+  });
+
+  it('treats userId-substring-but-not-prefix as foreign', () => {
+    // "user-12/x" must NOT match "user-1" — prefix must terminate at `/`
+    expect(() => assertOwnership({ bucket: 'b', path: 'user-12/x' }, 'user-1')).toThrow(
+      ForbiddenException,
+    );
+  });
+});

package/templates/apps/api/src/app/storage/assert-ownership.ts

@@ -0,0 +1,8 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { StorageRef } from '@icore/shared';
+
+export function assertOwnership(ref: StorageRef, userId: string): void {
+  if (!ref.path.startsWith(`${userId}/`)) {
+    throw new ForbiddenException('foreign_storage_ref');
+  }
+}