@apso/cli 0.44.0 → 0.45.0

package/dist/lib/templates/guards/jwt-auth.guard.eta

@@ -0,0 +1,172 @@
+/**
+ * AuthGuard - verifies <%= it.jwt.provider %> JWTs against the issuer's JWKS
+ *
+ * Auto-generated by Apso CLI from .apsorc auth configuration
+ * Generated at: <%= it.generatedAt %>
+ *
+ * This guard:
+ * - Reads the token from the Authorization: Bearer header
+ * - Verifies its signature with the issuer's published keys, plus issuer,
+ *   expiry<% if (it.jwt.audience) { %>, audience<% } %> and algorithm
+ * - Maps the token's claims into a normalized AuthContext on request.auth
+ *
+ * AUTH_JWT_ISSUER, AUTH_JWT_AUDIENCE and AUTH_JWKS_URI override the .apsorc
+ * values at runtime (for example a staging and a production tenant).
+ *
+ * DO NOT EDIT - Changes will be overwritten on next scaffold
+ */
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { createRemoteJWKSet, jwtVerify, JWTPayload } from 'jose';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+
+/**
+ * Decorator to mark a route as public (skips authentication)
+ * Usage: @Public()
+ */
+export const Public =
+  () => (target: any, key?: string, descriptor?: PropertyDescriptor) => {
+    Reflect.defineMetadata(IS_PUBLIC_KEY, true, descriptor?.value || target);
+  };
+
+/**
+ * Normalized auth context attached to authenticated requests.
+ * This is what scopeBy and RBAC consume.
+ */
+export interface AuthContext {
+  userId?: string;
+  email?: string;
+  workspaceId?: string;
+  organizationId?: string;
+  roles: string[];
+  claims: JWTPayload;
+}
+
+const ISSUER = process.env.AUTH_JWT_ISSUER || <%~ JSON.stringify(it.jwt.issuer) %>;
+const AUDIENCE = process.env.AUTH_JWT_AUDIENCE || <%~ JSON.stringify(it.jwt.audience || '') %>;
+const JWKS_URI = process.env.AUTH_JWKS_URI || <%~ JSON.stringify(it.jwt.jwksUri) %>;
+const ALGORITHMS = <%~ JSON.stringify(it.jwt.algorithms) %>;
+const AUTHORIZED_PARTIES = (process.env.AUTH_JWT_AUTHORIZED_PARTIES || <%~ JSON.stringify(it.jwt.authorizedParties.join(',')) %>)
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+const CLAIMS = <%~ JSON.stringify(it.jwt.claims) %> as Record<string, string | undefined>;
+
+/** A claim by exact name (Auth0 namespaced URLs contain dots), else by dotted path. */
+function claim(payload: JWTPayload, path?: string): unknown {
+  if (!path) return undefined;
+  if (path in payload) return (payload as any)[path];
+  return path.split('.').reduce((v: any, k) => (v == null ? undefined : v[k]), payload);
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' || typeof v === 'number' ? String(v) : undefined;
+
+function roles(v: unknown): string[] {
+  if (Array.isArray(v)) return v.map(String);
+  return typeof v === 'string' && v ? [v] : [];
+}
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  private readonly jwks = createRemoteJWKSet(new URL(JWKS_URI));
+
+  constructor(private reflector: Reflector) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) {
+      return true;
+    }
+
+    // The template's health check stays public for load balancer probes.
+    const req = context.switchToHttp().getRequest();
+    if (req.method === 'GET' && /^\/health\/?$/.test(req.path)) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest();
+    const header: string | undefined = request.headers.authorization;
+    if (!header || !header.startsWith('Bearer ')) {
+      throw new UnauthorizedException('No bearer token provided');
+    }
+
+    let payload: JWTPayload;
+    try {
+      ({ payload } = await jwtVerify(header.substring(7), this.jwks, {
+        issuer: ISSUER,
+        algorithms: ALGORITHMS,
+<% if (it.jwt.provider !== 'cognito') { %>
+        audience: AUDIENCE || undefined,
+<% } %>
+      }));
+    } catch {
+      throw new UnauthorizedException('Invalid token');
+    }
+<% if (it.jwt.provider === 'cognito') { %>
+    // Cognito ID tokens carry aud; access tokens carry client_id instead.
+    if (AUDIENCE) {
+      const aud = payload.aud ?? (payload as any).client_id;
+      if (!(Array.isArray(aud) ? aud.includes(AUDIENCE) : aud === AUDIENCE)) {
+        throw new UnauthorizedException('Invalid token');
+      }
+    }
+<% } %>
+
+    const azp = (payload as any).azp;
+    if (AUTHORIZED_PARTIES.length > 0 && azp !== undefined && !AUTHORIZED_PARTIES.includes(azp)) {
+      throw new UnauthorizedException('Invalid token');
+    }
+
+    const userId = str(claim(payload, CLAIMS.userId));
+    if (!userId) {
+      throw new UnauthorizedException('Token has no user id');
+    }
+    const tenant =
+      str(claim(payload, CLAIMS.workspaceId)) ??
+      str(claim(payload, CLAIMS.organizationId));
+    const auth: AuthContext = {
+      userId,
+      email: str(claim(payload, CLAIMS.email)),
+      workspaceId: tenant,
+      organizationId: tenant,
+      roles: roles(claim(payload, CLAIMS.roles)),
+      claims: payload,
+    };
+
+    request.auth = auth;
+    request.user = { id: userId, ...auth };
+    // Read by ScopeGuard's scope lookup.
+    request.workspaceId = tenant;
+    request.organizationId = tenant;
+    return true;
+  }
+}
+
+/**
+ * Helper function to get AuthContext from request
+ * Use this in controllers/services to access the authenticated context
+ */
+export function getAuthContext(request: any): AuthContext | undefined {
+  return request?.auth;
+}
+
+/**
+ * Helper function to require AuthContext (throws if not present)
+ */
+export function requireAuthContext(request: any): AuthContext {
+  const ctx = getAuthContext(request);
+  if (!ctx) {
+    throw new UnauthorizedException('Authentication required');
+  }
+  return ctx;
+}

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

@@ -28,7 +28,7 @@ export const SkipScopeCheck = () =>
     );
   };
 
-<% if (it.authConfig) { %>
+<% if (it.hasAuth) { %>
 /**
  * Import Public decorator from auth.guard to avoid duplicate exports
  */
@@ -246,7 +246,11 @@ export class ScopeGuard implements CanActivate {
       for (const scope of scopeConfig.scopes) {
         const expectedValue = this.getScopeValue(request, scope.contextKey);
         if (!expectedValue) {
+<% if (it.hasAuth) { %>
+          return false; // The caller has no tenant, so it owns no scoped rows
+<% } else { %>
           continue; // No scope value in context, skip this check
+<% } %>
         }
 
         let actualValue: any;
@@ -257,7 +261,8 @@ export class ScopeGuard implements CanActivate {
           actualValue = this.getNestedValue(entity, scope.path);
         }
 
-        if (actualValue !== expectedValue) {
+        // Token claims are strings; a numeric FK column reads back as a number.
+        if (actualValue == null || String(actualValue) !== String(expectedValue)) {
           return false;
         }
       }
@@ -277,9 +282,17 @@ export class ScopeGuard implements CanActivate {
     for (const scope of scopeConfig.scopes) {
       if (scope.direct) {
         const scopeValue = this.getScopeValue(request, scope.contextKey);
+<% if (it.hasAuth) { %>
+        if (!scopeValue) {
+          throw new ForbiddenException('No tenant in the auth context');
+        }
+        // Always the caller's tenant, never one from the body.
+        request.body[scope.field] = scopeValue;
+<% } else { %>
         if (scopeValue && !request.body[scope.field]) {
           request.body[scope.field] = scopeValue;
         }
+<% } %>
       }
     }
   }
@@ -292,6 +305,11 @@ export class ScopeGuard implements CanActivate {
     for (const scope of scopeConfig.scopes) {
       if (scope.direct) {
         const scopeValue = this.getScopeValue(request, scope.contextKey);
+<% if (it.hasAuth) { %>
+        if (!scopeValue) {
+          throw new ForbiddenException('No tenant in the auth context');
+        }
+<% } %>
         if (scopeValue) {
           // Add filter for @apso/crud
           request.query[`filter.${scope.field}`] = `$eq:${scopeValue}`;

package/dist/lib/templates/python/auth.eta

@@ -0,0 +1,217 @@
+<%~ includeFile('./header.eta', it) %>
+
+"""
+Authentication for every route on the generated /api router.
+
+<% if (it.jwt) { %>
+Verifies <%= it.jwt.provider %> JWTs from the Authorization: Bearer header against the
+issuer's published keys (JWKS), checks issuer, expiry<% if (it.jwt.audience) { %>, audience<% } %> and algorithm,
+and maps the token's claims into an AuthContext on request.state.auth.
+AUTH_JWT_ISSUER, AUTH_JWT_AUDIENCE and AUTH_JWKS_URI override the .apsorc values.
+<% } else { %>
+Reads an API key from the <%= it.apiKey.apiKeyHeader %> header and looks up the <%= it.apiKey.apiKeyEntity %> row
+whose <%= it.apiKey.keyField %> is the key's hex SHA-256.
+<% } %>
+"""
+<% if (it.apiKey) { %>
+import hashlib
+from datetime import date, datetime, timezone
+<% } else { %>
+import os
+<% } %>
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+<% if (it.jwt) { %>
+import jwt
+from fastapi import HTTPException, Request, status
+from jwt import PyJWKClient
+from starlette.concurrency import run_in_threadpool
+<% } else { %>
+from fastapi import Depends, HTTPException, Request, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from .models.<%= it.apiKey.pyModule %> import <%= it.apiKey.apiKeyEntity %>
+<% } %>
+
+
+@dataclass
+class AuthContext:
+    """The normalized identity of the caller."""
+
+    user_id: Optional[str] = None
+    email: Optional[str] = None
+    service_id: Optional[str] = None
+    workspace_id: Optional[str] = None
+    organization_id: Optional[str] = None
+    roles: List[str] = field(default_factory=list)
+    claims: dict = field(default_factory=dict)
+
+
+def get_auth_context(request: Request) -> Optional[AuthContext]:
+    """The authenticated caller, if any."""
+    return getattr(request.state, "auth", None)
+
+
+def _unauthorized(detail: str) -> HTTPException:
+    return HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=detail)
+<% if (it.jwt) { %>
+
+
+ISSUER = os.getenv("AUTH_JWT_ISSUER") or <%~ JSON.stringify(it.jwt.issuer) %>
+AUDIENCE = os.getenv("AUTH_JWT_AUDIENCE") or <%~ JSON.stringify(it.jwt.audience || '') %>
+JWKS_URI = os.getenv("AUTH_JWKS_URI") or <%~ JSON.stringify(it.jwt.jwksUri) %>
+ALGORITHMS = <%~ JSON.stringify(it.jwt.algorithms) %>
+# Origins allowed in the azp claim; empty allows any.
+AUTHORIZED_PARTIES = [
+    p.strip()
+    for p in (os.getenv("AUTH_JWT_AUTHORIZED_PARTIES") or <%~ JSON.stringify(it.jwt.authorizedParties.join(',')) %>).split(",")
+    if p.strip()
+]
+CLAIMS = <%~ JSON.stringify(it.jwt.claims) %>
+
+# Fetches and caches the issuer's keys on first use.
+_jwks = PyJWKClient(JWKS_URI, cache_keys=True)
+
+
+def _claim(payload: dict, path: Optional[str]) -> Any:
+    """A claim by exact name (Auth0 namespaced URLs contain dots), else by dotted path."""
+    if not path:
+        return None
+    if path in payload:
+        return payload[path]
+    value: Any = payload
+    for part in path.split("."):
+        if not isinstance(value, dict):
+            return None
+        value = value.get(part)
+    return value
+
+
+def _str(value: Any) -> Optional[str]:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (str, int, float)):
+        return str(value)
+    return None
+
+
+def _roles(value: Any) -> List[str]:
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    return [value] if isinstance(value, str) and value else []
+
+
+async def require_auth(request: Request) -> AuthContext:
+    """FastAPI dependency: verify the bearer token and attach the AuthContext."""
+    header = request.headers.get("authorization", "")
+    if not header.startswith("Bearer "):
+        raise _unauthorized("No bearer token provided")
+    token = header[len("Bearer "):]
+    try:
+        signing_key = await run_in_threadpool(_jwks.get_signing_key_from_jwt, token)
+    except jwt.PyJWKClientConnectionError:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Token signing keys unavailable",
+        )
+    except jwt.PyJWTError:
+        raise _unauthorized("Invalid token")
+    try:
+        payload = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=ALGORITHMS,
+            issuer=ISSUER,
+<% if (it.jwt.provider !== 'cognito') { %>
+            audience=AUDIENCE or None,
+            options={"require": ["exp", "iss"], "verify_aud": bool(AUDIENCE)},
+<% } else { %>
+            options={"require": ["exp", "iss"], "verify_aud": False},
+<% } %>
+        )
+    except jwt.PyJWTError:
+        raise _unauthorized("Invalid token")
+<% if (it.jwt.provider === 'cognito') { %>
+    # Cognito ID tokens carry aud; access tokens carry client_id instead.
+    if AUDIENCE:
+        aud = payload.get("aud", payload.get("client_id"))
+        if not (AUDIENCE in aud if isinstance(aud, list) else aud == AUDIENCE):
+            raise _unauthorized("Invalid token")
+<% } %>
+
+    azp = payload.get("azp")
+    if AUTHORIZED_PARTIES and azp is not None and azp not in AUTHORIZED_PARTIES:
+        raise _unauthorized("Invalid token")
+
+    user_id = _str(_claim(payload, CLAIMS.get("userId")))
+    if not user_id:
+        raise _unauthorized("Token has no user id")
+    tenant = _str(_claim(payload, CLAIMS.get("workspaceId"))) or _str(
+        _claim(payload, CLAIMS.get("organizationId"))
+    )
+    ctx = AuthContext(
+        user_id=user_id,
+        email=_str(_claim(payload, CLAIMS.get("email"))),
+        workspace_id=tenant,
+        organization_id=tenant,
+        roles=_roles(_claim(payload, CLAIMS.get("roles"))),
+        claims=payload,
+    )
+    request.state.auth = ctx
+    return ctx
+<% } else { %>
+
+
+def _expired(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value <= datetime.now(timezone.utc)
+    if isinstance(value, date):
+        return value <= date.today()
+    return False
+
+
+async def require_auth(request: Request, db: AsyncSession = Depends(get_db)) -> AuthContext:
+    """FastAPI dependency: authenticate the API key and attach the AuthContext."""
+    key = request.headers.get(<%~ JSON.stringify(it.apiKey.apiKeyHeader) %>)
+    if not key:
+        raise _unauthorized("No API key provided")
+    digest = hashlib.sha256(key.encode()).hexdigest()
+    result = await db.execute(
+        select(<%= it.apiKey.apiKeyEntity %>).where(<%= it.apiKey.apiKeyEntity %>.<%= it.apiKey.keyField %> == digest)
+    )
+    record = result.scalar_one_or_none()
+    if record is None:
+        raise _unauthorized("Invalid API key")
+<% if (it.apiKey.hasStatus) { %>
+    if getattr(record.status, "value", record.status) != "active":
+        raise _unauthorized("API key is not active")
+<% } %>
+<% if (it.apiKey.hasExpiresAt) { %>
+    if _expired(record.expiresAt):
+        raise _unauthorized("API key has expired")
+<% } %>
+
+    tenant = getattr(record, <%~ JSON.stringify(it.apiKey.workspaceField) %>, None)
+    tenant = str(tenant) if tenant is not None else None
+<% if (it.apiKey.roleField) { %>
+    role = getattr(record, <%~ JSON.stringify(it.apiKey.roleField) %>, None)
+    roles = [str(getattr(role, "value", role))] if role is not None else []
+<% } else { %>
+    roles: List[str] = []
+<% } %>
+    ctx = AuthContext(
+        service_id=str(record.id),
+        workspace_id=tenant,
+        organization_id=tenant,
+        roles=roles,
+    )
+    request.state.auth = ctx
+    return ctx
+<% } %>

package/dist/lib/templates/python/index-module.eta

@@ -1,13 +1,24 @@
 <%~ includeFile('./header.eta', it) %>
 
+<% if (it.hasAuth) { %>
+from fastapi import APIRouter, Depends
+
+from .auth import require_auth
+<% } else { %>
 from fastapi import APIRouter
+<% } %>
 
 <% it.entities.forEach((entity) => { %>
 from .routers.<%= entity.name.toLowerCase() %> import router as <%= entity.name.toLowerCase() %>_router
 <% }) %>
 
 # Create main router for autogenerated endpoints
+<% if (it.hasAuth) { %>
+# Every route on this router requires authentication (.apsorc auth).
+autogen_router = APIRouter(prefix="/api", dependencies=[Depends(require_auth)])
+<% } else { %>
 autogen_router = APIRouter(prefix="/api")
+<% } %>
 
 # Include all entity routers
 <% it.entities.forEach((entity) => { %>

package/dist/lib/templates/python/models/model-col-enum.eta

@@ -10,7 +10,7 @@ const pgEnumName = (it.entityName + '_' + it.field.name + '_enum').toLowerCase()
             enums.<%= enumTypeName %>,
             name="<%= pgEnumName %>",
             values_callable=lambda x: [e.value for e in x],
-            create_type=False
+            create_type=True
         ),
         nullable=<%= it.field.nullable === false ? 'False' : 'True' %>
     )

package/dist/lib/templates/python/schemas/schema.eta

@@ -5,12 +5,23 @@ from typing import Optional, List, Any
 from datetime import datetime, date
 from decimal import Decimal
 from uuid import UUID
-from pydantic import BaseModel, Field, ConfigDict
+from pydantic import BaseModel, Field, ConfigDict, field_serializer
+from sqlalchemy import inspect as sa_inspect
 <% if (it.importEnums) { -%>
 from ..models import enums
 <% } -%>
 
 
+
+def _columns(value: Any) -> Any:
+    """A related ORM row as its column values; its own relations are not loaded."""
+    if isinstance(value, list):
+        return [_columns(v) for v in value]
+    if not hasattr(value, "__table__"):
+        return value
+    return {a.key: getattr(value, a.key) for a in sa_inspect(value).mapper.column_attrs}
+
+
 class <%= it.entityName %>Base(BaseModel):
     """Base schema with common fields for <%= it.entityName %>"""
 <% it.columns.filter(c => !['id', 'createdAt', 'updatedAt', 'created_at', 'updated_at'].includes(c.name)).forEach((field) => { -%>
@@ -76,6 +87,16 @@ class <%= it.entityName %>(BaseModel):
 <% it.associations.filter(a => a.type === 'ManyToOne' || a.type === 'OneToOne').forEach((assoc) => { -%>
     <%= assoc.relationshipName %>: Optional[Any] = None
 <% }); -%>
+<% const relationFields = [
+  ...it.associations.filter(a => a.type === 'OneToMany' || a.type === 'ManyToMany').map(a => a.pluralizedRelationshipName),
+  ...it.associations.filter(a => a.type === 'ManyToOne' || a.type === 'OneToOne').map(a => a.relationshipName),
+]; -%>
+<% if (relationFields.length > 0) { -%>
+
+    @field_serializer(<%~ [...new Set(relationFields)].map(n => JSON.stringify(n)).join(', ') %>)
+    def _serialize_relations(self, value: Any) -> Any:
+        return _columns(value)
+<% } -%>
 
 
 class <%= it.entityName %>List(BaseModel):

package/dist/lib/templates/rest/controller-rest.eta

@@ -1,7 +1,7 @@
 <%~ includeFile('./header.eta') %>
 
 import { Controller, Body } from "@nestjs/common";
-import { Crud, CrudController, Override, ParsedRequest, CrudRequest, ParsedBody, CreateManyDto } from '@apso/crud';
+import { Crud, <% if (it.crudAuth.length) { %>CrudAuth, <% } %>CrudController, Override, ParsedRequest, CrudRequest, ParsedBody, CreateManyDto } from '@apso/crud';
 import { ApiTags, ApiResponse, ApiOperation, ApiBody } from '@nestjs/swagger';
 import {<%= it.entityName %>, <%= it.entityName %>Create, <%= it.entityName %>Update} from './dtos/<%= it.entityName%>.dto'
 import {<%= it.svcName %>} from './<%= it.entityName %>.service';
@@ -51,6 +51,21 @@ import {<%= it.svcName %>} from './<%= it.entityName %>.service';
         <% } %>
      }
 })
+<% if (it.crudAuth.length) { %>
+// Every query and write is limited to the caller's tenant (.apsorc scopeBy).
+@CrudAuth({
+    filter: (req: any) => ({
+<% it.crudAuth.forEach((s) => { %>
+        <%= s.field %>: req.<%= s.contextKey %> ?? req.user?.<%= s.contextKey %>,
+<% }) %>
+    }),
+    persist: (req: any) => ({
+<% it.crudAuth.forEach((s) => { %>
+        <%= s.field %>: req.<%= s.contextKey %> ?? req.user?.<%= s.contextKey %>,
+<% }) %>
+    }),
+})
+<% } %>
 
 @Controller('<%= it.pluralEntityName %>')
 @ApiTags('<%= it.pluralEntityName %>')

package/dist/lib/templates/rest/index-module-rest.eta

@@ -3,9 +3,15 @@
 <% it.entities.forEach((entity) => { %>
 import {<%= entity.name %>Module} from './<%= entity.name %>/<%= entity.name %>.module'
 <%}) %>
+<% if (it.hasGuards) { %>
+import { GuardsModule } from './guards/guards.module'
+<% } %>
 
 export default [
 <% it.entities.forEach((entity) => { %>
 <%= entity.name %>Module,
 <%}) %>
+<% if (it.hasGuards) { %>
+GuardsModule,
+<% } %>
 ]

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

@@ -1,7 +1,7 @@
 /**
  * Supported authentication provider types
  */
-export type AuthProviderType = "better-auth" | "custom-db-session" | "auth0" | "clerk" | "cognito" | "api-key";
+export type AuthProviderType = "better-auth" | "custom-db-session" | "auth0" | "clerk" | "cognito" | "jwt" | "api-key";
 /**
  * Base configuration common to all auth providers
  */
@@ -50,17 +50,25 @@ export interface JwtConfig {
      */
     issuer: string;
     /**
-     * Expected audience for the JWT
+     * Expected audience for the JWT. When omitted the audience is not checked
+     * (Clerk session tokens and Cognito access tokens carry no `aud` claim).
+     * For Cognito an access token's `client_id` is checked against it instead.
      */
-    audience: string;
+    audience?: string;
     /**
      * JWKS URI for key rotation. If not provided, uses issuer + /.well-known/jwks.json
      */
     jwksUri?: string;
     /**
-     * Algorithms to accept. Default: ["RS256"]
+     * Algorithms to accept. Default: ["RS256"]. Better Auth's JWT plugin signs
+     * with EdDSA by default.
      */
     algorithms?: string[];
+    /**
+     * Origins allowed in the token's `azp` claim (Clerk recommends this). A
+     * token whose azp is not listed is rejected; one without azp is accepted.
+     */
+    authorizedParties?: string[];
 }
 /**
  * Claim mapping for JWT providers
@@ -88,10 +96,11 @@ export interface JwtClaimsMapping {
     email?: string;
 }
 /**
- * Configuration for JWT-based providers (Auth0, Cognito, Clerk)
+ * Configuration for JWT-based providers (Auth0, Clerk, Cognito, or any issuer
+ * that publishes a JWKS via the generic "jwt" provider)
  */
 export interface JwtAuthConfig extends BaseAuthConfig {
-    provider: "auth0" | "clerk" | "cognito";
+    provider: "auth0" | "clerk" | "cognito" | "jwt";
     /**
      * JWT verification configuration
      */
@@ -119,7 +128,12 @@ export interface ApiKeyAuthConfig extends BaseAuthConfig {
      */
     apiKeyEntity?: string;
     /**
-     * Field name on apiKeyEntity for workspace/organization ID
+     * Field on apiKeyEntity holding the hex SHA-256 of the key. Default: "keyHash"
+     */
+    keyField?: string;
+    /**
+     * Field name on apiKeyEntity for workspace/organization ID.
+     * Default: "organizationId"
      */
     workspaceField?: string;
     /**
@@ -201,3 +215,23 @@ export declare function isJwtAuth(auth: AuthConfig): auth is JwtAuthConfig;
  * @returns {boolean} True if the auth config is API key based
  */
 export declare function isApiKeyAuth(auth: AuthConfig): auth is ApiKeyAuthConfig;
+/** A JWT auth config with every default filled in, as the templates use it. */
+export interface ResolvedJwtAuth {
+    provider: JwtAuthConfig["provider"];
+    issuer: string;
+    audience?: string;
+    jwksUri: string;
+    algorithms: string[];
+    authorizedParties: string[];
+    claims: Required<Pick<JwtClaimsMapping, "userId">> & Omit<JwtClaimsMapping, "userId">;
+}
+/** An API key auth config with every default filled in. */
+export type ResolvedApiKeyAuth = Required<Omit<ApiKeyAuthConfig, "roleField">> & Pick<ApiKeyAuthConfig, "roleField">;
+/**
+ * Fill JWT defaults and reject configs that would generate an unsafe check.
+ * Only asymmetric algorithms are accepted: the key comes from the issuer's
+ * JWKS, so there is no shared secret to configure or leak.
+ */
+export declare function resolveJwtAuth(auth: JwtAuthConfig): ResolvedJwtAuth;
+/** Fill API key defaults. */
+export declare function resolveApiKeyAuth(auth: ApiKeyAuthConfig): ResolvedApiKeyAuth;