@apso/cli 0.5.0 → 0.7.0

package/dist/lib/templates/guards/guards.module.eta

@@ -4,51 +4,111 @@ import { Module, Global } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { APP_GUARD } from '@nestjs/core';
 
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
 import { ScopeGuard } from './scope.guard';
+<% } %>
+<% if (it.authConfig) { %>
+import { AuthGuard } from './auth.guard';
+<% } %>
 
-<% /* Import all entities that have scopeBy defined */ %>
+<% /* Import all entities for ScopeGuard (from sibling autogen folders) */ %>
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
+// Entities for ScopeGuard
 <% it.scopedEntities.forEach((entity) => { %>
-import { <%= entity.name %> } from '../autogen/<%= entity.name %>/<%= entity.name %>.entity';
+import { <%= entity.name %> } from '../<%= entity.name %>/<%= entity.name %>.entity';
 <% }) %>
+<% } %>
+
+<% /* Import entities for AuthGuard (from sibling autogen folders) */ %>
+<% if (it.authConfig) { %>
+// Entities for AuthGuard
+import { <%= it.authConfig.sessionEntity %> } from '../<%= it.authConfig.sessionEntity %>/<%= it.authConfig.sessionEntity %>.entity';
+import { <%= it.authConfig.userEntity %> } from '../<%= it.authConfig.userEntity %>/<%= it.authConfig.userEntity %>.entity';
+<% if (it.authConfig.accountUserEntity) { %>
+import { <%= it.authConfig.accountUserEntity %> } from '../<%= it.authConfig.accountUserEntity %>/<%= it.authConfig.accountUserEntity %>.entity';
+<% } %>
+<% } %>
 
 /**
- * GuardsModule provides scope-based data isolation guards.
+ * GuardsModule provides authentication and scope-based data isolation guards.
  *
- * Auto-generated from .apsorc scopeBy definitions.
+ * Auto-generated from .apsorc configuration.
+ * Generated at: <%= it.generatedAt %>
  *
  * Usage:
  * 1. Import GuardsModule in your AppModule
  * 2. Guards are NOT enabled globally by default (for backward compatibility)
- * 3. To enable guards globally, uncomment the APP_GUARD provider below
- * 4. Or apply guards selectively using @UseGuards(ScopeGuard) on controllers/routes
+ * 3. To enable guards globally, uncomment the APP_GUARD providers below
+ * 4. Or apply guards selectively using @UseGuards(AuthGuard, ScopeGuard) on controllers
+ *
+<% if (it.authConfig) { %>
+ * AuthGuard:
+ * - Validates session tokens from cookies/headers
+ * - Loads user and organization context
+ * - Attaches normalized AuthContext to request.auth
+ * - Provider: <%= it.authConfig.provider %>
  *
- * When guards are enabled:
- * - All scoped routes enforce data isolation based on scopeBy config
- * - POST requests auto-inject scope fields from request context
+<% } %>
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
+ * ScopeGuard:
+ * - Enforces data isolation based on scopeBy config
+ * - POST requests auto-inject scope fields from request.auth
  * - GET requests auto-filter by scope fields
  * - GET/PUT/PATCH/DELETE by ID verify resource ownership
  *
+<% } %>
  * Decorators:
  * - @Public() - Skip all guards for a route
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
  * - @SkipScopeCheck() - Skip only scope checking
+<% } %>
  */
 @Global()
 @Module({
   imports: [
     TypeOrmModule.forFeature([
-<% it.scopedEntities.forEach((entity, index) => { %>
-      <%= entity.name %><%= index < it.scopedEntities.length - 1 ? ',' : '' %>
+<% /* Collect all unique entities */ %>
+<% const allEntities = new Set(); %>
+<% if (it.scopedEntities) { it.scopedEntities.forEach(e => allEntities.add(e.name)); } %>
+<% if (it.authConfig) { %>
+<%   allEntities.add(it.authConfig.sessionEntity); %>
+<%   allEntities.add(it.authConfig.userEntity); %>
+<%   if (it.authConfig.accountUserEntity) { allEntities.add(it.authConfig.accountUserEntity); } %>
+<% } %>
+<% const entityArray = Array.from(allEntities); %>
+<% entityArray.forEach((entity, index) => { %>
+      <%= entity %><%= index < entityArray.length - 1 ? ',' : '' %>
 <% }) %>
     ]),
   ],
   providers: [
+<% if (it.authConfig) { %>
+    AuthGuard,
+<% } %>
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
     ScopeGuard,
-    // UNCOMMENT BELOW TO ENABLE GLOBAL SCOPE ENFORCEMENT
+<% } %>
+    // UNCOMMENT BELOW TO ENABLE GLOBAL GUARDS
+<% if (it.authConfig) { %>
+    // {
+    //   provide: APP_GUARD,
+    //   useClass: AuthGuard,
+    // },
+<% } %>
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
     // {
     //   provide: APP_GUARD,
     //   useClass: ScopeGuard,
     // },
+<% } %>
+  ],
+  exports: [
+<% if (it.authConfig) { %>
+    AuthGuard,
+<% } %>
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
+    ScopeGuard,
+<% } %>
   ],
-  exports: [ScopeGuard],
 })
 export class GuardsModule {}

package/dist/lib/templates/guards/index.eta

@@ -1,4 +1,22 @@
 <%~ includeFile('../header.eta') %>
 
+<% if (it.authConfig) { %>
+export * from './auth.guard';
+<% } %>
+<% if (it.scopedEntities && it.scopedEntities.length > 0) { %>
+<% if (it.authConfig) { %>
+// When auth is configured, only export scope-specific items from scope.guard
+// to avoid duplicate exports (Public, IS_PUBLIC_KEY come from auth.guard)
+export {
+  ScopeGuard,
+  SKIP_SCOPE_CHECK,
+  SkipScopeCheck,
+  ScopeConfig,
+  ScopeField,
+  ENTITY_SCOPES,
+} from './scope.guard';
+<% } else { %>
 export * from './scope.guard';
+<% } %>
+<% } %>
 export * from './guards.module';

package/dist/lib/templates/guards/scope.guard.eta

@@ -10,9 +10,9 @@ import { Reflector } from '@nestjs/core';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 
-<% /* Import all entities that have scoped relationships */ %>
+<% /* Import all entities that have scoped relationships (from sibling autogen folders) */ %>
 <% it.scopedEntities.forEach((entity) => { %>
-import { <%= entity.name %> } from '../autogen/<%= entity.name %>/<%= entity.name %>.entity';
+import { <%= entity.name %> } from '../<%= entity.name %>/<%= entity.name %>.entity';
 <% }) %>
 
 /**
@@ -28,6 +28,13 @@ export const SkipScopeCheck = () =>
     );
   };
 
+<% if (it.authConfig) { %>
+/**
+ * Import Public decorator from auth.guard to avoid duplicate exports
+ */
+import { IS_PUBLIC_KEY, Public } from './auth.guard';
+export { IS_PUBLIC_KEY, Public };
+<% } else { %>
 /**
  * Decorator to mark routes as public (no auth required)
  */
@@ -40,6 +47,7 @@ export const Public = () =>
       descriptor?.value || target,
     );
   };
+<% } %>
 
 /**
  * Scope configuration for each entity
@@ -87,8 +95,8 @@ export const ENTITY_SCOPES: Record<string, ScopeConfig> = {
 <% }) %>
     ],
     injectOnCreate: <%= entity.injectOnCreate %>,
-    enforceOn: [<%= entity.enforceOn.map(op => `'${op}'`).join(', ') %>],
-    bypassRoles: [<%= entity.bypassRoles.map(role => `'${role}'`).join(', ') %>],
+    enforceOn: [<%~ entity.enforceOn.map(op => `'${op}'`).join(', ') %>],
+    bypassRoles: [<%~ entity.bypassRoles.map(role => `'${role}'`).join(', ') %>],
   }<%= index < it.scopedEntities.length - 1 ? ',' : '' %>
 <% }) %>
 };

package/dist/lib/types/auth.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Supported authentication provider types
+ */
+export type AuthProviderType = "better-auth" | "custom-db-session" | "auth0" | "clerk" | "cognito" | "api-key";
+/**
+ * Base configuration common to all auth providers
+ */
+export interface BaseAuthConfig {
+    /**
+     * The authentication provider type
+     */
+    provider: AuthProviderType;
+}
+/**
+ * Configuration for DB-backed session providers (Better Auth, custom-db-session)
+ */
+export interface DbSessionAuthConfig extends BaseAuthConfig {
+    provider: "better-auth" | "custom-db-session";
+    /**
+     * Entity name for sessions. Default: "session"
+     */
+    sessionEntity?: string;
+    /**
+     * Entity name for users. Default: "User"
+     */
+    userEntity?: string;
+    /**
+     * Junction entity for user-organization mapping. Default: "AccountUser"
+     */
+    accountUserEntity?: string;
+    /**
+     * Cookie name prefix for session tokens. Default: service name
+     */
+    cookiePrefix?: string;
+    /**
+     * Field name on accountUserEntity for organization ID. Default: "organizationId"
+     */
+    organizationField?: string;
+    /**
+     * Field name on accountUserEntity for user's role. Default: "role"
+     */
+    roleField?: string;
+}
+/**
+ * JWT configuration for token-based providers
+ */
+export interface JwtConfig {
+    /**
+     * The JWT issuer URL (e.g., "https://your-tenant.auth0.com/")
+     */
+    issuer: string;
+    /**
+     * Expected audience for the JWT
+     */
+    audience: string;
+    /**
+     * JWKS URI for key rotation. If not provided, uses issuer + /.well-known/jwks.json
+     */
+    jwksUri?: string;
+    /**
+     * Algorithms to accept. Default: ["RS256"]
+     */
+    algorithms?: string[];
+}
+/**
+ * Claim mapping for JWT providers
+ */
+export interface JwtClaimsMapping {
+    /**
+     * Claim for user ID. Default: "sub"
+     */
+    userId?: string;
+    /**
+     * Claim for workspace/organization ID
+     */
+    workspaceId?: string;
+    /**
+     * Claim for organization ID (alias for workspaceId)
+     */
+    organizationId?: string;
+    /**
+     * Claim for user roles array
+     */
+    roles?: string;
+    /**
+     * Claim for user email
+     */
+    email?: string;
+}
+/**
+ * Configuration for JWT-based providers (Auth0, Cognito, Clerk)
+ */
+export interface JwtAuthConfig extends BaseAuthConfig {
+    provider: "auth0" | "clerk" | "cognito";
+    /**
+     * JWT verification configuration
+     */
+    jwt: JwtConfig;
+    /**
+     * Mapping of JWT claims to AuthContext fields
+     */
+    claims?: JwtClaimsMapping;
+    /**
+     * Optional: If you want to sync/verify users against a local User entity
+     */
+    userEntity?: string;
+}
+/**
+ * Configuration for API key authentication
+ */
+export interface ApiKeyAuthConfig extends BaseAuthConfig {
+    provider: "api-key";
+    /**
+     * Header name for API key. Default: "x-api-key"
+     */
+    apiKeyHeader?: string;
+    /**
+     * Entity name for API keys. Default: "ApiKey"
+     */
+    apiKeyEntity?: string;
+    /**
+     * Field name on apiKeyEntity for workspace/organization ID
+     */
+    workspaceField?: string;
+    /**
+     * Field name on apiKeyEntity for role/permissions
+     */
+    roleField?: string;
+}
+/**
+ * Union type of all auth configurations
+ */
+export type AuthConfig = DbSessionAuthConfig | JwtAuthConfig | ApiKeyAuthConfig;
+/**
+ * The normalized AuthContext that all providers produce.
+ * This is what scopeBy and RBAC consume.
+ */
+export interface AuthContext {
+    /**
+     * The authenticated user's ID
+     */
+    userId?: string;
+    /**
+     * The user's email (if available)
+     */
+    email?: string;
+    /**
+     * The workspace/tenant ID (generic term)
+     */
+    workspaceId?: string;
+    /**
+     * The organization ID (alias for workspaceId in multi-tenant contexts)
+     */
+    organizationId?: string;
+    /**
+     * Array of roles/permissions the user has
+     */
+    roles: string[];
+    /**
+     * For API key auth: the service/key identifier
+     */
+    serviceId?: string;
+    /**
+     * Raw user object (provider-specific, for advanced use cases)
+     */
+    user?: unknown;
+    /**
+     * Raw session object (provider-specific, for advanced use cases)
+     */
+    session?: unknown;
+}
+/**
+ * Default values for DB session auth configuration
+ */
+export declare const DB_SESSION_AUTH_DEFAULTS: Required<Omit<DbSessionAuthConfig, "provider" | "cookiePrefix">> & {
+    cookiePrefix?: string;
+};
+/**
+ * Default values for JWT auth configuration
+ */
+export declare const JWT_AUTH_DEFAULTS: Required<Pick<JwtAuthConfig, "claims">> & Partial<JwtConfig>;
+/**
+ * Default values for API key auth configuration
+ */
+export declare const API_KEY_AUTH_DEFAULTS: Required<Omit<ApiKeyAuthConfig, "provider" | "workspaceField" | "roleField">>;
+/**
+ * Type guard: Check if auth config is DB session based
+ * @param {AuthConfig} auth - The auth configuration to check
+ * @returns {boolean} True if the auth config is DB session based
+ */
+export declare function isDbSessionAuth(auth: AuthConfig): auth is DbSessionAuthConfig;
+/**
+ * Type guard: Check if auth config is JWT based
+ * @param {AuthConfig} auth - The auth configuration to check
+ * @returns {boolean} True if the auth config is JWT based
+ */
+export declare function isJwtAuth(auth: AuthConfig): auth is JwtAuthConfig;
+/**
+ * Type guard: Check if auth config is API key based
+ * @param {AuthConfig} auth - The auth configuration to check
+ * @returns {boolean} True if the auth config is API key based
+ */
+export declare function isApiKeyAuth(auth: AuthConfig): auth is ApiKeyAuthConfig;

package/dist/lib/types/auth.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isApiKeyAuth = exports.isJwtAuth = exports.isDbSessionAuth = exports.API_KEY_AUTH_DEFAULTS = exports.JWT_AUTH_DEFAULTS = exports.DB_SESSION_AUTH_DEFAULTS = void 0;
+/**
+ * Default values for DB session auth configuration
+ */
+exports.DB_SESSION_AUTH_DEFAULTS = {
+    sessionEntity: "session",
+    userEntity: "User",
+    accountUserEntity: "AccountUser",
+    organizationField: "organizationId",
+    roleField: "role",
+    cookiePrefix: undefined, // Will use service name if not specified
+};
+/**
+ * Default values for JWT auth configuration
+ */
+exports.JWT_AUTH_DEFAULTS = {
+    claims: {
+        userId: "sub",
+        email: "email",
+        roles: "roles",
+    },
+};
+/**
+ * Default values for API key auth configuration
+ */
+exports.API_KEY_AUTH_DEFAULTS = {
+    apiKeyHeader: "x-api-key",
+    apiKeyEntity: "ApiKey",
+};
+/**
+ * Type guard: Check if auth config is DB session based
+ * @param {AuthConfig} auth - The auth configuration to check
+ * @returns {boolean} True if the auth config is DB session based
+ */
+function isDbSessionAuth(auth) {
+    return auth.provider === "better-auth" || auth.provider === "custom-db-session";
+}
+exports.isDbSessionAuth = isDbSessionAuth;
+/**
+ * Type guard: Check if auth config is JWT based
+ * @param {AuthConfig} auth - The auth configuration to check
+ * @returns {boolean} True if the auth config is JWT based
+ */
+function isJwtAuth(auth) {
+    return (auth.provider === "auth0" ||
+        auth.provider === "clerk" ||
+        auth.provider === "cognito");
+}
+exports.isJwtAuth = isJwtAuth;
+/**
+ * Type guard: Check if auth config is API key based
+ * @param {AuthConfig} auth - The auth configuration to check
+ * @returns {boolean} True if the auth config is API key based
+ */
+function isApiKeyAuth(auth) {
+    return auth.provider === "api-key";
+}
+exports.isApiKeyAuth = isApiKeyAuth;

package/dist/lib/types/entity.d.ts

@@ -5,7 +5,7 @@ import { Association } from "./relationship";
 /**
  * Operations that can have scope enforcement applied
  */
-export type ScopeOperation = 'find' | 'get' | 'create' | 'update' | 'delete';
+export type ScopeOperation = "find" | "get" | "create" | "update" | "delete";
 /**
  * Configuration options for scope enforcement behavior
  */
@@ -28,7 +28,7 @@ export interface Entity {
     name: string;
     created_at?: boolean;
     updated_at?: boolean;
-    primaryKeyType?: 'serial' | 'uuid';
+    primaryKeyType?: "serial" | "uuid";
     fields?: Field[];
     indexes?: Index[];
     uniques?: Unique[];

package/dist/lib/types/index.d.ts

@@ -3,3 +3,4 @@ export { FieldType, Field, ComputedField } from "./field";
 export { Index } from "./indices";
 export { JSONValue } from "./json";
 export { RelationshipType, Association, ApsorcRelationship, Relationship, RelationshipForTemplate, RelationshipMap, } from "./relationship";
+export { AuthProviderType, BaseAuthConfig, DbSessionAuthConfig, JwtConfig, JwtClaimsMapping, JwtAuthConfig, ApiKeyAuthConfig, AuthConfig, AuthContext, DB_SESSION_AUTH_DEFAULTS, JWT_AUTH_DEFAULTS, API_KEY_AUTH_DEFAULTS, isDbSessionAuth, isJwtAuth, isApiKeyAuth, } from "./auth";

package/dist/lib/types/index.js

@@ -1,2 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isApiKeyAuth = exports.isJwtAuth = exports.isDbSessionAuth = exports.API_KEY_AUTH_DEFAULTS = exports.JWT_AUTH_DEFAULTS = exports.DB_SESSION_AUTH_DEFAULTS = void 0;
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "DB_SESSION_AUTH_DEFAULTS", { enumerable: true, get: function () { return auth_1.DB_SESSION_AUTH_DEFAULTS; } });
+Object.defineProperty(exports, "JWT_AUTH_DEFAULTS", { enumerable: true, get: function () { return auth_1.JWT_AUTH_DEFAULTS; } });
+Object.defineProperty(exports, "API_KEY_AUTH_DEFAULTS", { enumerable: true, get: function () { return auth_1.API_KEY_AUTH_DEFAULTS; } });
+Object.defineProperty(exports, "isDbSessionAuth", { enumerable: true, get: function () { return auth_1.isDbSessionAuth; } });
+Object.defineProperty(exports, "isJwtAuth", { enumerable: true, get: function () { return auth_1.isJwtAuth; } });
+Object.defineProperty(exports, "isApiKeyAuth", { enumerable: true, get: function () { return auth_1.isApiKeyAuth; } });

package/dist/lib/types/relationship.d.ts

@@ -36,7 +36,7 @@ export interface RelationshipForTemplate extends Relationship {
     joinTable: boolean;
     biDirectional: boolean;
     inversePropertyName?: string;
-    referencedEntityPrimaryKeyType?: 'serial' | 'uuid';
+    referencedEntityPrimaryKeyType?: "serial" | "uuid";
 }
 export type RelationshipMap = {
     [key: string]: Relationship[];

package/dist/lib/utils/casing.js

@@ -2,16 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pascalCase = exports.snakeCase = exports.camelCase = void 0;
 function camelCase(str) {
-    return str
+    return (str
         // Insert a space before all caps that are followed by lower case (for PascalCase)
-        .replace(/([\da-z])([A-Z])/g, '$1 $2')
+        .replace(/([\da-z])([A-Z])/g, "$1 $2")
         // Replace all separators with spaces
-        .replace(/[ _-]+/g, ' ')
+        .replace(/[ _-]+/g, " ")
         // Lowercase the string, then uppercase the first letter of each word (except the first)
         .toLowerCase()
-        .replace(/ (\w)/g, (_, c) => c ? c.toUpperCase() : '')
+        .replace(/ (\w)/g, (_, c) => (c ? c.toUpperCase() : ""))
         // Remove spaces
-        .replace(/ /g, '');
+        .replace(/ /g, ""));
 }
 exports.camelCase = camelCase;
 const snakeCase = (str) => str[0].toLowerCase() +

package/dist/lib/utils/field.js

@@ -102,7 +102,8 @@ const validateDecimalField = (field) => {
         return;
     }
     // Validate precision
-    if (field.precision !== undefined && (field.precision < 1 || field.precision > 131072)) {
+    if (field.precision !== undefined &&
+        (field.precision < 1 || field.precision > 131072)) {
         throw new Error(`${field.name}: Invalid precision value ${field.precision}. Must be between 1 and 131072.`);
     }
     // Validate scale

package/dist/lib/utils/file-system.js

@@ -54,7 +54,7 @@ function withGeneratedMeta(data) {
     return {
         ...data,
         generatedAt: new Date().toISOString(),
-        generatedBy: process.env.USER || process.env.USERNAME || 'unknown',
+        generatedBy: process.env.USER || process.env.USERNAME || "unknown",
     };
 }
 exports.withGeneratedMeta = withGeneratedMeta;

package/dist/lib/utils/relationships/parse-v1.js

@@ -79,7 +79,8 @@ const parseV1Relationships = (entities) => {
     for (const apsorcRelationship of apsorcRelationships) {
         const parsedResult = (0, parse_1.parseRelationship)(apsorcRelationship, apsorcRelationships);
         for (const key of Object.keys(parsedResult)) {
-            if (parsedResult[key] && parsedResult[key].length > 0) { // Ensure non-empty result
+            if (parsedResult[key] && parsedResult[key].length > 0) {
+                // Ensure non-empty result
                 relationshipMap[key] = [
                     ...(relationshipMap[key] || []),
                     ...parsedResult[key],