@webpieces/core-util 0.3.263 → 0.3.264

package/src/http/decorators.d.ts

@@ -0,0 +1,212 @@
+import 'reflect-metadata';
+/**
+ * Metadata keys for storing API routing information.
+ * These keys are used by both server-side (routing) and client-side (client generation).
+ */
+export declare const METADATA_KEYS: {
+    API_PATH: string;
+    ENDPOINTS: string;
+    AUTH_META: string;
+    /** 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). */
+    API_KIND: string;
+    /** Per-method Cloud Tasks queue-name override (set via @Queue). */
+    QUEUE_OVERRIDE: string;
+};
+/**
+ * Route metadata stored per-method at runtime.
+ * Used internally by http-routing and http-client as the runtime representation
+ * of a route. Constructed from @ApiPath + @Endpoint metadata by createApiClient
+ * and ApiRoutingFactory.
+ */
+export declare class RouteMetadata {
+    httpMethod: string;
+    path: string;
+    methodName: string;
+    controllerClassName?: string;
+    authMeta?: AuthMeta;
+    constructor(httpMethod: string, path: string, methodName: string, controllerClassName?: string, authMeta?: AuthMeta);
+}
+/**
+ * The service-to-service / user auth mode of an endpoint. Discriminated union so
+ * a filter can `switch (mode.kind)` and get the data it needs, exhaustively.
+ *
+ * - `public`        → no auth check
+ * - `jwt`           → user-facing JWT (optionally role-gated), validated by the app AuthFilter
+ * - `oidc`          → Google OIDC service-to-service (Cloud Tasks delivery / cross-service RPC);
+ *                     `callers` is the allow-list of caller service accounts ('self' = this service's SA)
+ * - `shared-secret` → constant-time compare of a header against `process.env[secretEnv]`
+ */
+export type AuthMode = {
+    kind: 'public';
+} | {
+    kind: 'jwt';
+    roles: string[];
+} | {
+    kind: 'oidc';
+    callers: string[];
+} | {
+    kind: 'shared-secret';
+    secretEnv: string;
+};
+/**
+ * Auth metadata attached to a class or method via one of the auth decorators
+ * (@Public / @AuthJwt / @AuthOidc / @AuthSharedSecret) or the legacy @Authentication.
+ *
+ * Carries a discriminated {@link AuthMode}. The `authenticated`/`roles` getters are
+ * kept for back-compat with readers that only understand the user-JWT model
+ * (e.g. the example AuthFilter).
+ */
+export declare class AuthMeta {
+    mode: AuthMode;
+    constructor(mode: AuthMode);
+    /** True for every non-public mode (jwt, oidc, shared-secret). */
+    get authenticated(): boolean;
+    /** JWT roles, or empty for non-jwt modes. */
+    get roles(): string[];
+}
+/**
+ * @ApiPath(basePath) - Class decorator that marks a class as an API definition
+ * and sets the base path for all endpoints.
+ *
+ * Usage:
+ * ```typescript
+ * @Authentication({authenticated: true})
+ * @ApiPath('/api/save')
+ * abstract class SaveApi {
+ *   @Endpoint('/item')
+ *   save(request: SaveRequest): Promise<SaveResponse> { ... }
+ * }
+ * ```
+ */
+export declare function ApiPath(basePath: string): ClassDecorator;
+/**
+ * @Endpoint(path) - Method decorator that registers a POST endpoint at the given path.
+ *
+ * All endpoints are POST-only (matching gRPC/thrift style).
+ *
+ * Usage:
+ * ```typescript
+ * @Endpoint('/item')
+ * save(request: SaveRequest): Promise<SaveResponse> { ... }
+ * ```
+ */
+export declare function Endpoint(path: string): MethodDecorator;
+/**
+ * Authentication config passed to @Authentication() decorator.
+ */
+export declare class AuthenticationConfig {
+    authenticated: boolean;
+    roles?: string[];
+    constructor(authenticated: boolean, roles?: string[]);
+}
+/**
+ * @Authentication(config) - Class or method decorator for auth requirements.
+ *
+ * Single decorator replaces @Public/@Authenticated/@Roles:
+ * - @Authentication({authenticated: false}) → public, no auth check
+ * - @Authentication({authenticated: true}) → requires authentication
+ * - @Authentication({authenticated: true, roles: ['admin']}) → requires auth + roles
+ *
+ * Class-level is required. Methods can override class-level.
+ * Throws if authenticated=false but roles are specified (contradictory).
+ */
+export declare function Authentication(config: AuthenticationConfig): ClassDecorator & MethodDecorator;
+/**
+ * @Public() - endpoint requires no authentication. Class- or method-level.
+ */
+export declare function Public(): ClassDecorator & MethodDecorator;
+/**
+ * @AuthJwt(...roles) - user-facing JWT auth, optionally role-gated. The app-level
+ * AuthFilter validates the token; roles=[] means "any authenticated user".
+ */
+export declare function AuthJwt(...roles: string[]): ClassDecorator & MethodDecorator;
+/**
+ * @AuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery
+ * / cross-service RPC). `callers` is the allow-list of caller service accounts;
+ * defaults to ['self'] (only this service's own runtime SA, e.g. self-enqueue).
+ */
+export declare function AuthOidc(...callers: string[]): ClassDecorator & MethodDecorator;
+/**
+ * @AuthSharedSecret(envVarName) - constant-time compare of an inbound header against
+ * process.env[envVarName]. For internal callers that cannot mint OIDC tokens.
+ */
+export declare function AuthSharedSecret(envVarName: string): ClassDecorator & MethodDecorator;
+/**
+ * Get the base path from @ApiPath decorator.
+ */
+export declare function getApiPath(apiClass: Function): string | undefined;
+/**
+ * Get all endpoints from @Endpoint decorators.
+ * Returns a record of methodName -> endpoint path.
+ */
+export declare function getEndpoints(apiClass: Function): Record<string, string> | undefined;
+/**
+ * Check if a class has @ApiPath decorator.
+ */
+export declare function isApiPath(apiClass: Function): boolean;
+/**
+ * Get auth metadata for a specific method, falling back to class-level auth.
+ * Method-level auth takes precedence over class-level auth.
+ */
+export declare function getAuthMeta(apiClass: Function, methodName?: string): AuthMeta | undefined;
+/**
+ * Get the auth mode for a method (falling back to class-level), or undefined.
+ * Convenience wrapper over getAuthMeta for callers that only want the mode.
+ */
+export declare function getAuthMode(apiClass: Function, methodName?: string): AuthMode | undefined;
+/**
+ * Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server
+ * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth
+ * decorator is a startup error, never a silent open endpoint.
+ * @throws Error naming the first endpoint with no @Authentication/@Public/@Auth* decorator.
+ */
+export declare function assertEveryEndpointHasAuthMode(apiClass: Function): void;
+/**
+ * API kind. 'rpc' = synchronous request/response (http-client ↔ ApiRoutingFactory).
+ * 'pubsub' = fire-and-forget cloud task; the enqueue client (cloudtasks-client)
+ * schedules a Cloud Task that is later delivered to the SAME controller endpoint.
+ */
+export type ApiKind = 'rpc' | 'pubsub';
+/**
+ * @Rpc() - marks an API class as synchronous request/response (the default kind).
+ * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.
+ */
+export declare function Rpc(): ClassDecorator;
+/**
+ * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method
+ * MUST return Promise<void> (a compile-time contract on the abstract API). The
+ * enqueue client and the controller share this one class, exactly like RPC.
+ */
+export declare function PubSub(): ClassDecorator;
+/**
+ * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default
+ * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.
+ */
+export declare function Queue(name: string): MethodDecorator;
+/**
+ * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.
+ */
+export declare function getApiKind(apiClass: Function): ApiKind;
+/**
+ * Assert the API class is of the expected kind (used by the clients: the RPC
+ * client rejects a @PubSub api and vice-versa).
+ * @throws Error if the kind doesn't match.
+ */
+export declare function assertApiKind(apiClass: Function, expected: ApiKind): void;
+/**
+ * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub
+ * and declare at least one endpoint. (Return-type is Promise<void>, a compile-time
+ * contract — TS erases types at runtime so it cannot be re-checked here.)
+ * @throws Error if conventions are violated.
+ */
+export declare function assertPubSubConventions(apiClass: Function): void;
+/**
+ * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if
+ * present, else `${ApiClassName}-${methodName}`.
+ */
+export declare function getQueueName(apiClass: Function, methodName: string): string;
+/**
+ * Validate that a class/method doesn't have conflicting auth decorators.
+ * @throws Error if multiple @Authentication decorators are found on the same target.
+ */
+export declare function validateNoConflictingDecorators(apiClass: Function, methodName: string | undefined): void;

package/src/http/decorators.js

@@ -0,0 +1,365 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationConfig = exports.AuthMeta = exports.RouteMetadata = exports.METADATA_KEYS = void 0;
+exports.ApiPath = ApiPath;
+exports.Endpoint = Endpoint;
+exports.Authentication = Authentication;
+exports.Public = Public;
+exports.AuthJwt = AuthJwt;
+exports.AuthOidc = AuthOidc;
+exports.AuthSharedSecret = AuthSharedSecret;
+exports.getApiPath = getApiPath;
+exports.getEndpoints = getEndpoints;
+exports.isApiPath = isApiPath;
+exports.getAuthMeta = getAuthMeta;
+exports.getAuthMode = getAuthMode;
+exports.assertEveryEndpointHasAuthMode = assertEveryEndpointHasAuthMode;
+exports.Rpc = Rpc;
+exports.PubSub = PubSub;
+exports.Queue = Queue;
+exports.getApiKind = getApiKind;
+exports.assertApiKind = assertApiKind;
+exports.assertPubSubConventions = assertPubSubConventions;
+exports.getQueueName = getQueueName;
+exports.validateNoConflictingDecorators = validateNoConflictingDecorators;
+require("reflect-metadata");
+/**
+ * Metadata keys for storing API routing information.
+ * These keys are used by both server-side (routing) and client-side (client generation).
+ */
+exports.METADATA_KEYS = {
+    API_PATH: 'webpieces:api-path',
+    ENDPOINTS: 'webpieces:endpoints',
+    AUTH_META: 'webpieces:auth-meta',
+    /** 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). */
+    API_KIND: 'webpieces:api-kind',
+    /** Per-method Cloud Tasks queue-name override (set via @Queue). */
+    QUEUE_OVERRIDE: 'webpieces:queue-override',
+};
+/**
+ * Route metadata stored per-method at runtime.
+ * Used internally by http-routing and http-client as the runtime representation
+ * of a route. Constructed from @ApiPath + @Endpoint metadata by createApiClient
+ * and ApiRoutingFactory.
+ */
+class RouteMetadata {
+    httpMethod;
+    path;
+    methodName;
+    controllerClassName;
+    authMeta;
+    constructor(httpMethod, path, methodName, controllerClassName, authMeta) {
+        this.httpMethod = httpMethod;
+        this.path = path;
+        this.methodName = methodName;
+        this.controllerClassName = controllerClassName;
+        this.authMeta = authMeta;
+    }
+}
+exports.RouteMetadata = RouteMetadata;
+/**
+ * Auth metadata attached to a class or method via one of the auth decorators
+ * (@Public / @AuthJwt / @AuthOidc / @AuthSharedSecret) or the legacy @Authentication.
+ *
+ * Carries a discriminated {@link AuthMode}. The `authenticated`/`roles` getters are
+ * kept for back-compat with readers that only understand the user-JWT model
+ * (e.g. the example AuthFilter).
+ */
+class AuthMeta {
+    mode;
+    constructor(mode) {
+        this.mode = mode;
+    }
+    /** True for every non-public mode (jwt, oidc, shared-secret). */
+    get authenticated() {
+        return this.mode.kind !== 'public';
+    }
+    /** JWT roles, or empty for non-jwt modes. */
+    get roles() {
+        return this.mode.kind === 'jwt' ? this.mode.roles : [];
+    }
+}
+exports.AuthMeta = AuthMeta;
+/**
+ * @ApiPath(basePath) - Class decorator that marks a class as an API definition
+ * and sets the base path for all endpoints.
+ *
+ * Usage:
+ * ```typescript
+ * @Authentication({authenticated: true})
+ * @ApiPath('/api/save')
+ * abstract class SaveApi {
+ *   @Endpoint('/item')
+ *   save(request: SaveRequest): Promise<SaveResponse> { ... }
+ * }
+ * ```
+ */
+function ApiPath(basePath) {
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target) => {
+        Reflect.defineMetadata(exports.METADATA_KEYS.API_PATH, basePath, target);
+        // Initialize endpoints map if not exists
+        if (!Reflect.hasMetadata(exports.METADATA_KEYS.ENDPOINTS, target)) {
+            Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINTS, {}, target);
+        }
+    };
+}
+/**
+ * @Endpoint(path) - Method decorator that registers a POST endpoint at the given path.
+ *
+ * All endpoints are POST-only (matching gRPC/thrift style).
+ *
+ * Usage:
+ * ```typescript
+ * @Endpoint('/item')
+ * save(request: SaveRequest): Promise<SaveResponse> { ... }
+ * ```
+ */
+function Endpoint(path) {
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target, propertyKey, _descriptor) => {
+        const metadataTarget = typeof target === 'function' ? target : target.constructor;
+        const endpoints = Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINTS, metadataTarget) || {};
+        endpoints[propertyKey] = path;
+        Reflect.defineMetadata(exports.METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);
+    };
+}
+/**
+ * Authentication config passed to @Authentication() decorator.
+ */
+class AuthenticationConfig {
+    authenticated;
+    roles;
+    constructor(authenticated, roles) {
+        this.authenticated = authenticated;
+        this.roles = roles;
+    }
+}
+exports.AuthenticationConfig = AuthenticationConfig;
+/**
+ * @Authentication(config) - Class or method decorator for auth requirements.
+ *
+ * Single decorator replaces @Public/@Authenticated/@Roles:
+ * - @Authentication({authenticated: false}) → public, no auth check
+ * - @Authentication({authenticated: true}) → requires authentication
+ * - @Authentication({authenticated: true, roles: ['admin']}) → requires auth + roles
+ *
+ * Class-level is required. Methods can override class-level.
+ * Throws if authenticated=false but roles are specified (contradictory).
+ */
+function Authentication(config) {
+    // Validate: can't be public with roles
+    if (!config.authenticated && config.roles && config.roles.length > 0) {
+        throw new Error(`Invalid @Authentication config: authenticated=false but roles=${JSON.stringify(config.roles)}. ` +
+            `Cannot require roles on a public endpoint. Set authenticated=true or remove roles.`);
+    }
+    const mode = config.authenticated
+        ? { kind: 'jwt', roles: config.roles ?? [] }
+        : { kind: 'public' };
+    return defineAuthMode(mode);
+}
+/**
+ * Shared implementation for every auth decorator: stores an {@link AuthMeta} for
+ * the given {@link AuthMode} at class- or method-level, rejecting a second auth
+ * decorator on the same target.
+ */
+function defineAuthMode(mode) {
+    const authMeta = new AuthMeta(mode);
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target, propertyKey, _descriptor) => {
+        if (propertyKey !== undefined) {
+            // Method decorator
+            const metadataTarget = typeof target === 'function' ? target : target.constructor;
+            validateNoConflictingDecorators(metadataTarget, propertyKey);
+            Reflect.defineMetadata(exports.METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);
+        }
+        else {
+            // Class decorator
+            validateNoConflictingDecorators(target, undefined);
+            Reflect.defineMetadata(exports.METADATA_KEYS.AUTH_META, authMeta, target);
+        }
+    };
+}
+/**
+ * @Public() - endpoint requires no authentication. Class- or method-level.
+ */
+function Public() {
+    return defineAuthMode({ kind: 'public' });
+}
+/**
+ * @AuthJwt(...roles) - user-facing JWT auth, optionally role-gated. The app-level
+ * AuthFilter validates the token; roles=[] means "any authenticated user".
+ */
+function AuthJwt(...roles) {
+    return defineAuthMode({ kind: 'jwt', roles });
+}
+/**
+ * @AuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery
+ * / cross-service RPC). `callers` is the allow-list of caller service accounts;
+ * defaults to ['self'] (only this service's own runtime SA, e.g. self-enqueue).
+ */
+function AuthOidc(...callers) {
+    return defineAuthMode({ kind: 'oidc', callers: callers.length > 0 ? callers : ['self'] });
+}
+/**
+ * @AuthSharedSecret(envVarName) - constant-time compare of an inbound header against
+ * process.env[envVarName]. For internal callers that cannot mint OIDC tokens.
+ */
+function AuthSharedSecret(envVarName) {
+    return defineAuthMode({ kind: 'shared-secret', secretEnv: envVarName });
+}
+// ============================================================
+// Helper functions
+// ============================================================
+/**
+ * Get the base path from @ApiPath decorator.
+ */
+function getApiPath(apiClass) {
+    return Reflect.getMetadata(exports.METADATA_KEYS.API_PATH, apiClass);
+}
+/**
+ * Get all endpoints from @Endpoint decorators.
+ * Returns a record of methodName -> endpoint path.
+ */
+function getEndpoints(apiClass) {
+    return Reflect.getMetadata(exports.METADATA_KEYS.ENDPOINTS, apiClass);
+}
+/**
+ * Check if a class has @ApiPath decorator.
+ */
+function isApiPath(apiClass) {
+    return Reflect.hasMetadata(exports.METADATA_KEYS.API_PATH, apiClass);
+}
+/**
+ * Get auth metadata for a specific method, falling back to class-level auth.
+ * Method-level auth takes precedence over class-level auth.
+ */
+function getAuthMeta(apiClass, methodName) {
+    // Check method-level first
+    if (methodName) {
+        const methodAuth = Reflect.getMetadata(exports.METADATA_KEYS.AUTH_META, apiClass, methodName);
+        if (methodAuth) {
+            return methodAuth;
+        }
+    }
+    // Fall back to class-level
+    return Reflect.getMetadata(exports.METADATA_KEYS.AUTH_META, apiClass);
+}
+/**
+ * Get the auth mode for a method (falling back to class-level), or undefined.
+ * Convenience wrapper over getAuthMeta for callers that only want the mode.
+ */
+function getAuthMode(apiClass, methodName) {
+    return getAuthMeta(apiClass, methodName)?.mode;
+}
+/**
+ * Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server
+ * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth
+ * decorator is a startup error, never a silent open endpoint.
+ * @throws Error naming the first endpoint with no @Authentication/@Public/@Auth* decorator.
+ */
+function assertEveryEndpointHasAuthMode(apiClass) {
+    const apiName = apiClass.name || 'Unknown';
+    const endpoints = getEndpoints(apiClass) || {};
+    for (const methodName of Object.keys(endpoints)) {
+        if (!getAuthMeta(apiClass, methodName)) {
+            throw new Error(`Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +
+                `Add @Public(), @AuthJwt(...), @AuthOidc(...) or @AuthSharedSecret(...) ` +
+                `to the class or method.`);
+        }
+    }
+}
+/**
+ * @Rpc() - marks an API class as synchronous request/response (the default kind).
+ * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.
+ */
+function Rpc() {
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target) => {
+        Reflect.defineMetadata(exports.METADATA_KEYS.API_KIND, 'rpc', target);
+    };
+}
+/**
+ * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method
+ * MUST return Promise<void> (a compile-time contract on the abstract API). The
+ * enqueue client and the controller share this one class, exactly like RPC.
+ */
+function PubSub() {
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target) => {
+        Reflect.defineMetadata(exports.METADATA_KEYS.API_KIND, 'pubsub', target);
+    };
+}
+/**
+ * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default
+ * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.
+ */
+function Queue(name) {
+    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
+    return (target, propertyKey, _descriptor) => {
+        const metadataTarget = typeof target === 'function' ? target : target.constructor;
+        const overrides = Reflect.getMetadata(exports.METADATA_KEYS.QUEUE_OVERRIDE, metadataTarget) || {};
+        overrides[propertyKey] = name;
+        Reflect.defineMetadata(exports.METADATA_KEYS.QUEUE_OVERRIDE, overrides, metadataTarget);
+    };
+}
+/**
+ * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.
+ */
+function getApiKind(apiClass) {
+    return Reflect.getMetadata(exports.METADATA_KEYS.API_KIND, apiClass) ?? 'rpc';
+}
+/**
+ * Assert the API class is of the expected kind (used by the clients: the RPC
+ * client rejects a @PubSub api and vice-versa).
+ * @throws Error if the kind doesn't match.
+ */
+function assertApiKind(apiClass, expected) {
+    const actual = getApiKind(apiClass);
+    if (actual !== expected) {
+        const apiName = apiClass.name || 'Unknown';
+        throw new Error(`API ${apiName} is @${actual === 'pubsub' ? 'PubSub' : 'Rpc'} but a ` +
+            `${expected === 'pubsub' ? '@PubSub (cloud task)' : '@Rpc'} API was required here.`);
+    }
+}
+/**
+ * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub
+ * and declare at least one endpoint. (Return-type is Promise<void>, a compile-time
+ * contract — TS erases types at runtime so it cannot be re-checked here.)
+ * @throws Error if conventions are violated.
+ */
+function assertPubSubConventions(apiClass) {
+    assertApiKind(apiClass, 'pubsub');
+    const apiName = apiClass.name || 'Unknown';
+    if (!isApiPath(apiClass)) {
+        throw new Error(`@PubSub API ${apiName} must also be decorated with @ApiPath()`);
+    }
+    const endpoints = getEndpoints(apiClass) || {};
+    if (Object.keys(endpoints).length === 0) {
+        throw new Error(`@PubSub API ${apiName} declares no @Endpoint methods`);
+    }
+}
+/**
+ * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if
+ * present, else `${ApiClassName}-${methodName}`.
+ */
+function getQueueName(apiClass, methodName) {
+    const overrides = Reflect.getMetadata(exports.METADATA_KEYS.QUEUE_OVERRIDE, apiClass) || {};
+    return overrides[methodName] ?? `${apiClass.name || 'Unknown'}-${methodName}`;
+}
+/**
+ * Validate that a class/method doesn't have conflicting auth decorators.
+ * @throws Error if multiple @Authentication decorators are found on the same target.
+ */
+function validateNoConflictingDecorators(apiClass, methodName) {
+    const existing = methodName
+        ? Reflect.getMetadata(exports.METADATA_KEYS.AUTH_META, apiClass, methodName)
+        : Reflect.getMetadata(exports.METADATA_KEYS.AUTH_META, apiClass);
+    if (existing) {
+        const targetName = apiClass.name || 'Unknown';
+        const location = methodName ? `method '${methodName}' of ${targetName}` : `class ${targetName}`;
+        throw new Error(`Conflicting @Authentication on ${location}. ` +
+            `Only one @Authentication() decorator allowed per target.`);
+    }
+}
+//# sourceMappingURL=decorators.js.map

package/src/http/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/decorators.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\n\n/**\n * Metadata keys for storing API routing information.\n * These keys are used by both server-side (routing) and client-side (client generation).\n */\nexport const METADATA_KEYS = {\n    API_PATH: 'webpieces:api-path',\n    ENDPOINTS: 'webpieces:endpoints',\n    AUTH_META: 'webpieces:auth-meta',\n    /** 'rpc' (default, sync request/response) vs 'pubsub' (fire-and-forget cloud task). */\n    API_KIND: 'webpieces:api-kind',\n    /** Per-method Cloud Tasks queue-name override (set via @Queue). */\n    QUEUE_OVERRIDE: 'webpieces:queue-override',\n};\n\n/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by createApiClient\n * and ApiRoutingFactory.\n */\nexport class RouteMetadata {\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n    }\n}\n\n/**\n * The service-to-service / user auth mode of an endpoint. Discriminated union so\n * a filter can `switch (mode.kind)` and get the data it needs, exhaustively.\n *\n * - `public`        → no auth check\n * - `jwt`           → user-facing JWT (optionally role-gated), validated by the app AuthFilter\n * - `oidc`          → Google OIDC service-to-service (Cloud Tasks delivery / cross-service RPC);\n *                     `callers` is the allow-list of caller service accounts ('self' = this service's SA)\n * - `shared-secret` → constant-time compare of a header against `process.env[secretEnv]`\n */\nexport type AuthMode =\n    | { kind: 'public' }\n    | { kind: 'jwt'; roles: string[] }\n    | { kind: 'oidc'; callers: string[] }\n    | { kind: 'shared-secret'; secretEnv: string };\n\n/**\n * Auth metadata attached to a class or method via one of the auth decorators\n * (@Public / @AuthJwt / @AuthOidc / @AuthSharedSecret) or the legacy @Authentication.\n *\n * Carries a discriminated {@link AuthMode}. The `authenticated`/`roles` getters are\n * kept for back-compat with readers that only understand the user-JWT model\n * (e.g. the example AuthFilter).\n */\nexport class AuthMeta {\n    mode: AuthMode;\n\n    constructor(mode: AuthMode) {\n        this.mode = mode;\n    }\n\n    /** True for every non-public mode (jwt, oidc, shared-secret). */\n    get authenticated(): boolean {\n        return this.mode.kind !== 'public';\n    }\n\n    /** JWT roles, or empty for non-jwt modes. */\n    get roles(): string[] {\n        return this.mode.kind === 'jwt' ? this.mode.roles : [];\n    }\n}\n\n/**\n * @ApiPath(basePath) - Class decorator that marks a class as an API definition\n * and sets the base path for all endpoints.\n *\n * Usage:\n * ```typescript\n * @Authentication({authenticated: true})\n * @ApiPath('/api/save')\n * abstract class SaveApi {\n *   @Endpoint('/item')\n *   save(request: SaveRequest): Promise<SaveResponse> { ... }\n * }\n * ```\n */\nexport function ApiPath(basePath: string): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_PATH, basePath, target);\n\n        // Initialize endpoints map if not exists\n        if (!Reflect.hasMetadata(METADATA_KEYS.ENDPOINTS, target)) {\n            Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, {}, target);\n        }\n    };\n}\n\n/**\n * @Endpoint(path) - Method decorator that registers a POST endpoint at the given path.\n *\n * All endpoints are POST-only (matching gRPC/thrift style).\n *\n * Usage:\n * ```typescript\n * @Endpoint('/item')\n * save(request: SaveRequest): Promise<SaveResponse> { ... }\n * ```\n */\nexport function Endpoint(path: string): MethodDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n\n        const endpoints: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, metadataTarget) || {};\n\n        endpoints[propertyKey as string] = path;\n\n        Reflect.defineMetadata(METADATA_KEYS.ENDPOINTS, endpoints, metadataTarget);\n    };\n}\n\n/**\n * Authentication config passed to @Authentication() decorator.\n */\nexport class AuthenticationConfig {\n    authenticated: boolean;\n    roles?: string[];\n\n    constructor(authenticated: boolean, roles?: string[]) {\n        this.authenticated = authenticated;\n        this.roles = roles;\n    }\n}\n\n/**\n * @Authentication(config) - Class or method decorator for auth requirements.\n *\n * Single decorator replaces @Public/@Authenticated/@Roles:\n * - @Authentication({authenticated: false}) → public, no auth check\n * - @Authentication({authenticated: true}) → requires authentication\n * - @Authentication({authenticated: true, roles: ['admin']}) → requires auth + roles\n *\n * Class-level is required. Methods can override class-level.\n * Throws if authenticated=false but roles are specified (contradictory).\n */\nexport function Authentication(config: AuthenticationConfig): ClassDecorator & MethodDecorator {\n    // Validate: can't be public with roles\n    if (!config.authenticated && config.roles && config.roles.length > 0) {\n        throw new Error(\n            `Invalid @Authentication config: authenticated=false but roles=${JSON.stringify(config.roles)}. ` +\n            `Cannot require roles on a public endpoint. Set authenticated=true or remove roles.`\n        );\n    }\n\n    const mode: AuthMode = config.authenticated\n        ? { kind: 'jwt', roles: config.roles ?? [] }\n        : { kind: 'public' };\n    return defineAuthMode(mode);\n}\n\n/**\n * Shared implementation for every auth decorator: stores an {@link AuthMeta} for\n * the given {@link AuthMode} at class- or method-level, rejecting a second auth\n * decorator on the same target.\n */\nfunction defineAuthMode(mode: AuthMode): ClassDecorator & MethodDecorator {\n    const authMeta = new AuthMeta(mode);\n\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => {\n        if (propertyKey !== undefined) {\n            // Method decorator\n            const metadataTarget = typeof target === 'function' ? target : target.constructor;\n            validateNoConflictingDecorators(metadataTarget, propertyKey as string);\n            Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, metadataTarget, propertyKey);\n        } else {\n            // Class decorator\n            validateNoConflictingDecorators(target, undefined);\n            Reflect.defineMetadata(METADATA_KEYS.AUTH_META, authMeta, target);\n        }\n    };\n}\n\n/**\n * @Public() - endpoint requires no authentication. Class- or method-level.\n */\nexport function Public(): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'public' });\n}\n\n/**\n * @AuthJwt(...roles) - user-facing JWT auth, optionally role-gated. The app-level\n * AuthFilter validates the token; roles=[] means \"any authenticated user\".\n */\nexport function AuthJwt(...roles: string[]): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'jwt', roles });\n}\n\n/**\n * @AuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery\n * / cross-service RPC). `callers` is the allow-list of caller service accounts;\n * defaults to ['self'] (only this service's own runtime SA, e.g. self-enqueue).\n */\nexport function AuthOidc(...callers: string[]): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'oidc', callers: callers.length > 0 ? callers : ['self'] });\n}\n\n/**\n * @AuthSharedSecret(envVarName) - constant-time compare of an inbound header against\n * process.env[envVarName]. For internal callers that cannot mint OIDC tokens.\n */\nexport function AuthSharedSecret(envVarName: string): ClassDecorator & MethodDecorator {\n    return defineAuthMode({ kind: 'shared-secret', secretEnv: envVarName });\n}\n\n// ============================================================\n// Helper functions\n// ============================================================\n\n/**\n * Get the base path from @ApiPath decorator.\n */\nexport function getApiPath(apiClass: Function): string | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/**\n * Get all endpoints from @Endpoint decorators.\n * Returns a record of methodName -> endpoint path.\n */\nexport function getEndpoints(apiClass: Function): Record<string, string> | undefined {\n    return Reflect.getMetadata(METADATA_KEYS.ENDPOINTS, apiClass);\n}\n\n/**\n * Check if a class has @ApiPath decorator.\n */\nexport function isApiPath(apiClass: Function): boolean {\n    return Reflect.hasMetadata(METADATA_KEYS.API_PATH, apiClass);\n}\n\n/**\n * Get auth metadata for a specific method, falling back to class-level auth.\n * Method-level auth takes precedence over class-level auth.\n */\nexport function getAuthMeta(apiClass: Function, methodName?: string): AuthMeta | undefined {\n    // Check method-level first\n    if (methodName) {\n        const methodAuth = Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName);\n        if (methodAuth) {\n            return methodAuth;\n        }\n    }\n\n    // Fall back to class-level\n    return Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n}\n\n/**\n * Get the auth mode for a method (falling back to class-level), or undefined.\n * Convenience wrapper over getAuthMeta for callers that only want the mode.\n */\nexport function getAuthMode(apiClass: Function, methodName?: string): AuthMode | undefined {\n    return getAuthMeta(apiClass, methodName)?.mode;\n}\n\n/**\n * Fail-fast at wiring time if any endpoint lacks an auth mode. Both the server\n * (ApiRoutingFactory) and the task/rpc clients call this so a missing auth\n * decorator is a startup error, never a silent open endpoint.\n * @throws Error naming the first endpoint with no @Authentication/@Public/@Auth* decorator.\n */\nexport function assertEveryEndpointHasAuthMode(apiClass: Function): void {\n    const apiName = apiClass.name || 'Unknown';\n    const endpoints = getEndpoints(apiClass) || {};\n    for (const methodName of Object.keys(endpoints)) {\n        if (!getAuthMeta(apiClass, methodName)) {\n            throw new Error(\n                `Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +\n                `Add @Public(), @AuthJwt(...), @AuthOidc(...) or @AuthSharedSecret(...) ` +\n                `to the class or method.`,\n            );\n        }\n    }\n}\n\n// ============================================================\n// API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n// ============================================================\n\n/**\n * API kind. 'rpc' = synchronous request/response (http-client ↔ ApiRoutingFactory).\n * 'pubsub' = fire-and-forget cloud task; the enqueue client (cloudtasks-client)\n * schedules a Cloud Task that is later delivered to the SAME controller endpoint.\n */\nexport type ApiKind = 'rpc' | 'pubsub';\n\n/**\n * @Rpc() - marks an API class as synchronous request/response (the default kind).\n * Present mostly for symmetry/readability; an undecorated API is treated as 'rpc'.\n */\nexport function Rpc(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'rpc' as ApiKind, target);\n    };\n}\n\n/**\n * @PubSub() - marks an API class as fire-and-forget over Cloud Tasks. Every method\n * MUST return Promise<void> (a compile-time contract on the abstract API). The\n * enqueue client and the controller share this one class, exactly like RPC.\n */\nexport function PubSub(): ClassDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any) => {\n        Reflect.defineMetadata(METADATA_KEYS.API_KIND, 'pubsub' as ApiKind, target);\n    };\n}\n\n/**\n * @Queue(name) - override the Cloud Tasks queue name for a @PubSub method. Default\n * (no decorator) is `${ApiClassName}-${methodName}`, matched 1:1 by Terraform.\n */\nexport function Queue(name: string): MethodDecorator {\n    // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any\n    return (target: any, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n        const metadataTarget = typeof target === 'function' ? target : target.constructor;\n        const overrides: Record<string, string> =\n            Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, metadataTarget) || {};\n        overrides[propertyKey as string] = name;\n        Reflect.defineMetadata(METADATA_KEYS.QUEUE_OVERRIDE, overrides, metadataTarget);\n    };\n}\n\n/**\n * Get the API kind. Defaults to 'rpc' when neither @Rpc nor @PubSub is present.\n */\nexport function getApiKind(apiClass: Function): ApiKind {\n    return (Reflect.getMetadata(METADATA_KEYS.API_KIND, apiClass) as ApiKind) ?? 'rpc';\n}\n\n/**\n * Assert the API class is of the expected kind (used by the clients: the RPC\n * client rejects a @PubSub api and vice-versa).\n * @throws Error if the kind doesn't match.\n */\nexport function assertApiKind(apiClass: Function, expected: ApiKind): void {\n    const actual = getApiKind(apiClass);\n    if (actual !== expected) {\n        const apiName = apiClass.name || 'Unknown';\n        throw new Error(\n            `API ${apiName} is @${actual === 'pubsub' ? 'PubSub' : 'Rpc'} but a ` +\n            `${expected === 'pubsub' ? '@PubSub (cloud task)' : '@Rpc'} API was required here.`,\n        );\n    }\n}\n\n/**\n * Validate @PubSub conventions at wiring time: the class must be @ApiPath + @PubSub\n * and declare at least one endpoint. (Return-type is Promise<void>, a compile-time\n * contract — TS erases types at runtime so it cannot be re-checked here.)\n * @throws Error if conventions are violated.\n */\nexport function assertPubSubConventions(apiClass: Function): void {\n    assertApiKind(apiClass, 'pubsub');\n    const apiName = apiClass.name || 'Unknown';\n    if (!isApiPath(apiClass)) {\n        throw new Error(`@PubSub API ${apiName} must also be decorated with @ApiPath()`);\n    }\n    const endpoints = getEndpoints(apiClass) || {};\n    if (Object.keys(endpoints).length === 0) {\n        throw new Error(`@PubSub API ${apiName} declares no @Endpoint methods`);\n    }\n}\n\n/**\n * Resolve the Cloud Tasks queue name for a @PubSub method: the @Queue override if\n * present, else `${ApiClassName}-${methodName}`.\n */\nexport function getQueueName(apiClass: Function, methodName: string): string {\n    const overrides: Record<string, string> =\n        Reflect.getMetadata(METADATA_KEYS.QUEUE_OVERRIDE, apiClass) || {};\n    return overrides[methodName] ?? `${apiClass.name || 'Unknown'}-${methodName}`;\n}\n\n/**\n * Validate that a class/method doesn't have conflicting auth decorators.\n * @throws Error if multiple @Authentication decorators are found on the same target.\n */\nexport function validateNoConflictingDecorators(apiClass: Function, methodName: string | undefined): void {\n    const existing = methodName\n        ? Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass, methodName)\n        : Reflect.getMetadata(METADATA_KEYS.AUTH_META, apiClass);\n\n    if (existing) {\n        const targetName = apiClass.name || 'Unknown';\n        const location = methodName ? `method '${methodName}' of ${targetName}` : `class ${targetName}`;\n        throw new Error(\n            `Conflicting @Authentication on ${location}. ` +\n            `Only one @Authentication() decorator allowed per target.`\n        );\n    }\n}\n"]}