@webpieces/core-util 0.4.760 → 0.4.762

package/src/http/decorators.d.ts

@@ -10,6 +10,8 @@ export declare const METADATA_KEYS: {
     API_PATH: string;
     ENDPOINTS: string;
     AUTH_META: string;
+    /** Method names carrying one of the canonical authorization decorators. */
+    AUTH_METHODS: 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). */
@@ -54,14 +56,14 @@ export interface EndpointOptions {
     formPost?: boolean;
     /**
      * RETAIN the verbatim request bytes + the absolute url the sender addressed, so an
-     * {@link AuthWebhook} hook can verify a vendor signature over them (see `RawRequest`).
+     * {@link WpAuthWebhook} hook can verify a vendor signature over them (see `RawRequest`).
      *
      * Opt-in PER ENDPOINT, sitting beside `formPost` and for the same reason: the cost lands on the
      * handful of webhook routes rather than on every request in the process. It is retention, not
      * new buffering — the express adapter already accumulates the whole body, it simply threw it
      * away once it had parsed a DTO.
      *
-     * REQUIRED by `@AuthWebhook`, checked at wiring time (see
+     * REQUIRED by `@WpAuthWebhook`, checked at wiring time (see
      * {@link assertEveryWebhookEndpointRetainsRawBody}) rather than left to fail as a 401 in
      * production: a hook with nothing to verify is a misconfiguration, not a bad request.
      *
@@ -86,9 +88,9 @@ export interface ExternalEndpointOptions extends EndpointOptions {
  *
  * Usage:
  * ```typescript
- * @AuthJwt({ roles: ['admin'] })
  * @ApiPath('/api/save')
  * abstract class SaveApi {
+ *   @WpAuthJwt({ roles: ['admin'] })
  *   @Endpoint('/item', 'rpc')
  *   save(request: SaveRequest): Promise<SaveResponse> { ... }
  * }
@@ -160,23 +162,24 @@ export declare function MaskLog(fields: Record<string, MaskMode>): MethodDecorat
  */
 export declare function getMaskSpec(apiClass: Function, methodName: string): MaskSpec | undefined;
 /**
- * @Public() - endpoint requires no authentication. Class- or method-level.
+ * @WpAuthPublic(reason) - endpoint intentionally requires no authentication.
+ * The non-empty reason makes anonymous exposure an explicit review decision.
  */
-export declare function Public(): ClassDecorator & MethodDecorator;
+export declare function WpAuthPublic(reason: string): MethodDecorator;
 /**
- * @AuthJwt(requirement) - THE user-facing JWT decorator, covering the whole user-JWT axis: the
+ * @WpAuthJwt(requirement) - THE user-facing JWT decorator, covering the whole user-JWT axis: the
  * compiler-enforced role decision ({@link JwtRoles}) plus app-defined fields ({@link JwtRequirement}).
  *
  * ```typescript
- * @AuthJwt({ roles: ['admin', 'editor'] })          // any-of
- * @AuthJwt({ allRolesAllowed: true, inOrg: true })  // wide + an app rule enforced by authorizeJwt
+ * @WpAuthJwt({ roles: ['admin', 'editor'] })          // any-of
+ * @WpAuthJwt({ allRolesAllowed: true, inOrg: true })  // wide + an app rule enforced by authorizeJwt
  * ```
  *
  * It absorbed the former `@Auth(requirement)` — same argument, same AuthMode, so two spellings of one
- * decision. One decorator per credential kind now: `@Public` / `@AuthJwt` / `@AuthOidc` /
- * `@AuthSharedSecret` / `@AuthLocalOnly`.
+ * decision. One decorator per credential kind now: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /
+ * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.
  */
-export declare function AuthJwt(requirement: JwtRequirement): ClassDecorator & MethodDecorator;
+export declare function WpAuthJwt(requirement: JwtRequirement): MethodDecorator;
 /**
  * The roles an endpoint accepts, or [] when it accepts every authenticated user. The ONE reader of
  * the {@link JwtRoles} union, so no caller has to re-derive "does absent mean wide?" — a question
@@ -184,38 +187,38 @@ export declare function AuthJwt(requirement: JwtRequirement): ClassDecorator & M
  */
 export declare function rolesRequired(requirement: JwtRequirement): readonly string[];
 /**
- * @AuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery / cross-service
+ * @WpAuthOidc(...callers) - Google OIDC service-to-service auth (Cloud Tasks delivery / cross-service
  * RPC). `callers` is an OPTIONAL app-level allow-list of caller service accounts.
  *
  * NO args = TRUST THE EDGE: accept any genuine Google-signed OIDC caller, because a PRIVATE Cloud
  * Run service's edge already gates WHO via `run.invoker` IAM (managed in terraform — one source of
  * truth, no hand-synced list in code). If the service is actually PUBLIC, the verifier logs a loud
- * warning (it can't be the gate then). Pass explicit SAs (`@AuthOidc('svc-a')`) only when you want
+ * warning (it can't be the gate then). Pass explicit SAs (`@WpAuthOidc('svc-a')`) only when you want
  * an additional app-level allow-list as defense-in-depth.
  */
-export declare function AuthOidc(...callers: string[]): ClassDecorator & MethodDecorator;
+export declare function WpAuthOidc(...callers: string[]): MethodDecorator;
 /**
- * @AuthSharedSecret(key) - constant-time compare of an inbound header against the secret bound for
+ * @WpAuthSharedSecret(key) - constant-time compare of an inbound header against the secret bound for
  * `key`. `key` is a LOOKUP KEY (not an env var): the server looks up its accepted {@link SharedSecrets}
  * by this key, and each client looks up the value it sends by the SAME key (see {@link Secrets}).
  * For internal callers that cannot mint OIDC tokens.
  */
-export declare function AuthSharedSecret(key: string): ClassDecorator & MethodDecorator;
+export declare function WpAuthSharedSecret(key: string): MethodDecorator;
 /**
- * @AuthWebhook(name) - an OUTSIDE vendor signed this request in its OWN scheme; the app's bound
+ * @WpAuthWebhook(name) - an OUTSIDE vendor signed this request in its OWN scheme; the app's bound
  * `WebhookAuthCallback` proves it. THE mode for every signed inbound webhook — Sentry, GitHub, Stripe, Slack,
  * Twilio — none of which fits the other kinds: no vendor mints Google OIDC tokens, and none sends its
- * secret (they all send a DERIVATION over the request), so `@Public` was the only reachable posture
+ * secret (they all send a DERIVATION over the request), so `@WpAuthPublic` was the only reachable posture
  * and `calledBy: 'sentry'` stayed a claim rather than a fact.
  *
  * ```typescript
- * @AuthWebhook('sentry')
+ * @WpAuthWebhook('sentry')
  * @Endpoint('/hook/sentry/issue', 'external', { calledBy: 'sentry', rawBody: true })
  * abstract notify(request: SentryIssueHook): Promise<HookAck>;
  * ```
  *
  * `name` is a bare STRING resolved through DI in the server's container, exactly as
- * `@AuthOidc('gmail-push')` already is — never a function reference. An api contract is level 0: a
+ * `@WpAuthOidc('gmail-push')` already is — never a function reference. An api contract is level 0: a
  * direct reference to a verifier would invert the dependency graph and drag a vendor SDK into the
  * browser bundle that imports the same contract.
  *
@@ -227,18 +230,18 @@ export declare function AuthSharedSecret(key: string): ClassDecorator & MethodDe
  * call the vendor's own library — hence the REQUIRED `{ rawBody: true }` (see
  * {@link EndpointOptions.rawBody}), which is checked at wiring time.
  *
- * FAILS CLOSED: with no `WebhookAuthCallback` bound, every `@AuthWebhook` endpoint 401s, matching `JwtHook`.
+ * FAILS CLOSED: with no `WebhookAuthCallback` bound, every `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.
  * Silently allowing an unverified webhook is the one default that must not exist.
  */
-export declare function AuthWebhook(name: string): ClassDecorator & MethodDecorator;
+export declare function WpAuthWebhook(name: string): MethodDecorator;
 /**
- * @AuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`
+ * @WpAuthApiKey(regime, credentials) - a CUSTOMER holds the credential. The app's bound `ApiKeyHook`
  * authenticates the inbound request against its own datastore and returns the `ContextTuple` entries
  * the framework seeds into `RequestContext`. THE mode for a partner-facing contract consumed by other
  * companies' codebases (POS vendors, back-office platforms, ETL pipelines).
  *
  * ```typescript
- * @AuthApiKey('onetablet-partner', [
+ * @WpAuthApiKey('onetablet-partner', [
  *     { in: 'header', name: 'x-api-key', description: 'The key issued to your integration.' },
  *     { in: 'header', name: 'x-organization-id', description: 'Which of your organizations to act on.' },
  * ])
@@ -247,7 +250,7 @@ export declare function AuthWebhook(name: string): ClassDecorator & MethodDecora
  * ```
  *
  * `regime` is a bare STRING selecting WHICH key regime this route belongs to, exactly as
- * `@AuthSharedSecret(key)` and `@AuthWebhook(vendor)` already are — one hook serves several regimes,
+ * `@WpAuthSharedSecret(key)` and `@WpAuthWebhook(vendor)` already are — one hook serves several regimes,
  * and an api contract is level 0, so it never references a verifier directly.
  *
  * `credentials` DECLARES where the credential rides ({@link ApiKeyCredential}), so a spec generator
@@ -265,10 +268,10 @@ export declare function AuthWebhook(name: string): ClassDecorator & MethodDecora
  * exists to remove. That is a compile error, not a runtime throw (see {@link JwtRoles}'s non-empty
  * tuple, the same device for the same reason).
  *
- * WHY IT IS NOT `@AuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other
+ * WHY IT IS NOT `@WpAuthSharedSecret`. Shared-secret declares that AN INTERNAL SERVICE is on the other
  * end, so the framework BELIEVES the trusted context headers that caller forwarded (see
  * `DestinationTrust.forAuthMode` and `AuthFilter.verifiesCaller`). A customer is not an internal
- * service: declaring a partner endpoint `@AuthSharedSecret` would let that partner assert someone
+ * service: declaring a partner endpoint `@WpAuthSharedSecret` would let that partner assert someone
  * else's org id on the wire and have it admitted — a privilege escalation. `apikey` therefore sits
  * with `jwt` on the caller-NOT-verified side, where an inbound trusted header is admitted only when
  * the hook independently derived the SAME value.
@@ -280,16 +283,17 @@ export declare function AuthWebhook(name: string): ClassDecorator & MethodDecora
  * PAIR. `credentials` does NOT change that: the framework reads no header from it and performs no
  * extraction. It is DECLARATION for readers of the contract, and enforcement stays entirely the hook's.
  *
- * FAILS CLOSED: with no `ApiKeyHook` bound, every `@AuthApiKey` endpoint 401s, matching `JwtHook` and
+ * FAILS CLOSED: with no `ApiKeyHook` bound, every `@WpAuthApiKey` endpoint 401s, matching `JwtHook` and
  * `WebhookAuthCallback`.
  */
-export declare function AuthApiKey(regime: string, credentials: ApiKeyCredentials): ClassDecorator & MethodDecorator;
+export declare function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator;
 /**
- * @AuthLocalOnly() - this endpoint exists ONLY on a developer's machine. Off-local it is not
- * registered as a route at all, and if it is somehow reached it 404s. Class- or method-level.
+ * @WpAuthLocalOnly() - this endpoint exists ONLY on a developer's machine. Off-local it is not
+ * registered as a route at all, and if it is somehow reached it 404s. Method-only, like every
+ * authorization decorator, so every endpoint's posture is visible at the method.
  *
  * ```typescript
- * @AuthLocalOnly()
+ * @WpAuthLocalOnly()
  * @Endpoint('/logs', 'rpc')
  * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }
  * ```
@@ -298,11 +302,11 @@ export declare function AuthApiKey(regime: string, credentials: ApiKeyCredential
  * sync by a comment: a route module that registered the route only locally, PLUS a
  * `if (env !== 'local') throw new ForbiddenError(...)` at the top of the handler. Neither half
  * was visible on the CONTRACT, so nothing reading the api — a human, a generated client, or an
- * agent — could tell this endpoint from a `@Public` one. Both halves are the framework's job now,
+ * agent — could tell this endpoint from a `@WpAuthPublic` one. Both halves are the framework's job now,
  * driven by this ONE declaration on the contract, which is where every other "who may call this"
  * fact already lives.
  *
- * It is DELIBERATELY a peer of @Public / @AuthJwt / @AuthOidc / @AuthSharedSecret / @AuthApiKey rather than an
+ * It is DELIBERATELY a peer of @WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthApiKey rather than an
  * option on one of them: one decorator per credential kind, and "local-only" is a different kind of
  * gate — it authenticates nobody, it excludes an entire environment.
  *
@@ -310,7 +314,7 @@ export declare function AuthApiKey(regime: string, credentials: ApiKeyCredential
  * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint
  * rather than exposing it.
  */
-export declare function AuthLocalOnly(): ClassDecorator & MethodDecorator;
+export declare function WpAuthLocalOnly(): MethodDecorator;
 /**
  * Get the base path from @ApiPath decorator.
  */
@@ -352,20 +356,20 @@ export declare function assertEveryExternalEndpointDeclaresCaller(apiClass: Func
 export declare function isFormPost(apiClass: Function, methodName: string): boolean;
 /**
  * True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the
- * verbatim bytes + absolute url for an {@link AuthWebhook} hook to verify.
+ * verbatim bytes + absolute url for an {@link WpAuthWebhook} hook to verify.
  */
 export declare function isRawBody(apiClass: Function, methodName: string): boolean;
 /**
- * Fail-fast at wiring time when an `@AuthWebhook` endpoint did not ask the transport to keep the
+ * Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the
  * bytes it is supposed to verify. A hook with nothing to verify is a MISCONFIGURATION, and it must
  * surface at startup, naming the fix — not as a 401 in production on exactly the traffic the endpoint
  * exists for.
  *
  * This pairing is a runtime assert rather than a type because the two halves live on DIFFERENT
- * decorators (`@AuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say
+ * decorators (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say
  * anything about the other's.
  *
- * @throws Error naming the first `@AuthWebhook` endpoint missing `{ rawBody: true }`.
+ * @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.
  */
 export declare function assertEveryWebhookEndpointRetainsRawBody(apiClass: Function): void;
 /**
@@ -373,15 +377,14 @@ export declare function assertEveryWebhookEndpointRetainsRawBody(apiClass: Funct
  */
 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.
+ * Get method-level auth metadata. Class-level authorization is forbidden.
  */
-export declare function getAuthMeta(apiClass: Function, methodName?: string): AuthMeta | undefined;
+export declare function getAuthMeta(apiClass: Function, methodName: string): AuthMeta | undefined;
 /**
- * Get the auth mode for a method (falling back to class-level), or undefined.
+ * Get the auth mode for a method, or undefined.
  * Convenience wrapper over getAuthMeta for callers that only want the mode.
  */
-export declare function getAuthMode(apiClass: Function, methodName?: string): AuthMode | undefined;
+export declare function getAuthMode(apiClass: Function, methodName: string): AuthMode | undefined;
 /**
  * The ONE prescription for "this endpoint declares no auth", shared by the two places that raise it
  * (here and http-routing's ApiRoutingFactory) because they had drifted into teaching different menus.