@webpieces/core-util 0.4.863 → 0.4.864

package/src/http/authorization.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthorizationDeclaration = exports.AUTHORIZATION_METHODS_KEY = exports.AUTHORIZATION_METADATA_KEY = exports.AuthorizationType = void 0;
+exports.WpAuthorization = WpAuthorization;
+exports.getAuthorization = getAuthorization;
+require("reflect-metadata");
+var AuthorizationType;
+(function (AuthorizationType) {
+    AuthorizationType["ALL_USERS"] = "all-users";
+    AuthorizationType["ROLES"] = "roles";
+    AuthorizationType["SERVICE_ONLY"] = "service-only";
+    AuthorizationType["USERS_OR_SERVICES"] = "users-or-services";
+    AuthorizationType["ANONYMOUS"] = "anonymous";
+    AuthorizationType["CUSTOM"] = "custom";
+})(AuthorizationType || (exports.AuthorizationType = AuthorizationType = {}));
+exports.AUTHORIZATION_METADATA_KEY = 'webpieces:authorization';
+exports.AUTHORIZATION_METHODS_KEY = 'webpieces:authorization-methods';
+/** Runtime checks also protect JavaScript and type-erased callers. */
+class AuthorizationDeclaration {
+    // webpieces-disable no-any-unknown -- decorator policy is application-owned and validated before storage
+    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration
+    static validate(value) {
+        if (!value || typeof value !== 'object' || !Object.values(AuthorizationType).includes(value.authType)) {
+            throw new Error('@WpAuthorization requires a recognized AuthorizationType.');
+        }
+        const allowed = new Set(['authType']);
+        if (value.authType === AuthorizationType.ROLES)
+            allowed.add('roles');
+        if (value.authType === AuthorizationType.ANONYMOUS)
+            allowed.add('reason');
+        if (value.authType === AuthorizationType.CUSTOM)
+            allowed.add('appPolicy');
+        for (const key of Object.keys(value)) {
+            if (!allowed.has(key))
+                throw new Error(`@WpAuthorization ${value.authType} rejects '${key}'; application policy belongs in CUSTOM.appPolicy.`);
+        }
+        if (value.authType === AuthorizationType.ROLES &&
+            (!Array.isArray(value.roles) || value.roles.length === 0 || value.roles.some((role) => typeof role !== 'string' || role.trim() === ''))) {
+            throw new Error('@WpAuthorization ROLES requires a nonempty tuple of nonempty role names.');
+        }
+        if (value.authType === AuthorizationType.ANONYMOUS &&
+            (typeof value.reason !== 'string' || value.reason.trim() === '')) {
+            throw new Error('@WpAuthorization ANONYMOUS requires a nonempty reason.');
+        }
+        if (value.authType === AuthorizationType.CUSTOM && !Object.hasOwn(value, 'appPolicy')) {
+            throw new Error('@WpAuthorization CUSTOM requires appPolicy and a bound AuthorizationHook.');
+        }
+    }
+}
+exports.AuthorizationDeclaration = AuthorizationDeclaration;
+// webpieces-disable no-function-outside-class -- canonical TypeScript method decorator factory
+function WpAuthorization(policy) {
+    AuthorizationDeclaration.validate(policy);
+    return (target, propertyKey) => {
+        if (propertyKey === undefined)
+            throw new Error('@WpAuthorization is method-only.');
+        const apiClass = target.constructor;
+        if (Reflect.hasMetadata(exports.AUTHORIZATION_METADATA_KEY, apiClass, propertyKey)) {
+            throw new Error(`Duplicate @WpAuthorization on ${apiClass.name}.${String(propertyKey)}.`);
+        }
+        Reflect.defineMetadata(exports.AUTHORIZATION_METADATA_KEY, Object.freeze(policy), apiClass, propertyKey);
+        const methods = new Set(Reflect.getMetadata(exports.AUTHORIZATION_METHODS_KEY, apiClass) ?? []);
+        methods.add(String(propertyKey));
+        Reflect.defineMetadata(exports.AUTHORIZATION_METHODS_KEY, [...methods], apiClass);
+    };
+}
+// webpieces-disable no-function-outside-class -- canonical Reflect metadata reader; webpieces-disable no-any-unknown -- erased custom policy is validated by the application hook at startup
+function getAuthorization(apiClass, methodName) {
+    return Reflect.getMetadata(exports.AUTHORIZATION_METADATA_KEY, apiClass, methodName);
+}
+//# sourceMappingURL=authorization.js.map

package/src/http/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/authorization.ts"],"names":[],"mappings":"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","sourcesContent":["import 'reflect-metadata';\n\nexport enum AuthorizationType {\n    ALL_USERS = 'all-users',\n    ROLES = 'roles',\n    SERVICE_ONLY = 'service-only',\n    USERS_OR_SERVICES = 'users-or-services',\n    ANONYMOUS = 'anonymous',\n    CUSTOM = 'custom',\n}\n\nexport type AuthorizationRequirement<TPolicy = never> =\n    | {\n          authType: AuthorizationType.ALL_USERS | AuthorizationType.SERVICE_ONLY | AuthorizationType.USERS_OR_SERVICES;\n          roles?: never;\n          reason?: never;\n          appPolicy?: never;\n      }\n    | {\n          authType: AuthorizationType.ROLES;\n          roles: readonly [string, ...string[]];\n          reason?: never;\n          appPolicy?: never;\n      }\n    | {\n          authType: AuthorizationType.ANONYMOUS;\n          reason: string;\n          roles?: never;\n          appPolicy?: never;\n      }\n    | {\n          authType: AuthorizationType.CUSTOM;\n          appPolicy: TPolicy;\n          roles?: never;\n          reason?: never;\n      };\n\nexport const AUTHORIZATION_METADATA_KEY = 'webpieces:authorization';\nexport const AUTHORIZATION_METHODS_KEY = 'webpieces:authorization-methods';\n\n/** Runtime checks also protect JavaScript and type-erased callers. */\nexport class AuthorizationDeclaration {\n    // webpieces-disable no-any-unknown -- decorator policy is application-owned and validated before storage\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    static validate(value: AuthorizationRequirement<unknown>): void {\n        if (!value || typeof value !== 'object' || !Object.values(AuthorizationType).includes(value.authType)) {\n            throw new Error('@WpAuthorization requires a recognized AuthorizationType.');\n        }\n        const allowed = new Set(['authType']);\n        if (value.authType === AuthorizationType.ROLES) allowed.add('roles');\n        if (value.authType === AuthorizationType.ANONYMOUS) allowed.add('reason');\n        if (value.authType === AuthorizationType.CUSTOM) allowed.add('appPolicy');\n        for (const key of Object.keys(value)) {\n            if (!allowed.has(key)) throw new Error(`@WpAuthorization ${value.authType} rejects '${key}'; application policy belongs in CUSTOM.appPolicy.`);\n        }\n        if (value.authType === AuthorizationType.ROLES &&\n            (!Array.isArray(value.roles) || value.roles.length === 0 || value.roles.some((role: string) => typeof role !== 'string' || role.trim() === ''))) {\n            throw new Error('@WpAuthorization ROLES requires a nonempty tuple of nonempty role names.');\n        }\n        if (value.authType === AuthorizationType.ANONYMOUS &&\n            (typeof value.reason !== 'string' || value.reason.trim() === '')) {\n            throw new Error('@WpAuthorization ANONYMOUS requires a nonempty reason.');\n        }\n        if (value.authType === AuthorizationType.CUSTOM && !Object.hasOwn(value, 'appPolicy')) {\n            throw new Error('@WpAuthorization CUSTOM requires appPolicy and a bound AuthorizationHook.');\n        }\n    }\n}\n\n// webpieces-disable no-function-outside-class -- canonical TypeScript method decorator factory\nexport function WpAuthorization<TPolicy = never>(policy: AuthorizationRequirement<TPolicy>): MethodDecorator {\n    AuthorizationDeclaration.validate(policy);\n    return (target: object, propertyKey: string | symbol) => {\n        if (propertyKey === undefined) throw new Error('@WpAuthorization is method-only.');\n        const apiClass = target.constructor;\n        if (Reflect.hasMetadata(AUTHORIZATION_METADATA_KEY, apiClass, propertyKey)) {\n            throw new Error(`Duplicate @WpAuthorization on ${apiClass.name}.${String(propertyKey)}.`);\n        }\n        Reflect.defineMetadata(AUTHORIZATION_METADATA_KEY, Object.freeze(policy), apiClass, propertyKey);\n        const methods = new Set<string>(Reflect.getMetadata(AUTHORIZATION_METHODS_KEY, apiClass) ?? []);\n        methods.add(String(propertyKey));\n        Reflect.defineMetadata(AUTHORIZATION_METHODS_KEY, [...methods], apiClass);\n    };\n}\n\n// webpieces-disable no-function-outside-class -- canonical Reflect metadata reader; webpieces-disable no-any-unknown -- erased custom policy is validated by the application hook at startup\nexport function getAuthorization(apiClass: Function, methodName: string): AuthorizationRequirement<unknown> | undefined {\n    return Reflect.getMetadata(AUTHORIZATION_METADATA_KEY, apiClass, methodName);\n}\n"]}

package/src/http/decorators.d.ts

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 import { MaskSpec, MaskMode } from './LogFieldMask';
-import { ApiKeyCredentials, AuthMeta, AuthMode, JwtRequirement } from './auth-mode';
+import { AuthMeta, AuthMethods } from './auth-mode';
 import { EndpointOperation, EndpointOptions, ExternalEndpointOptions } from './HttpEndpointOptions';
 import { HttpMethod } from './HttpContract';
 export type { EndpointOptions, ExternalEndpointOptions } from './HttpEndpointOptions';
@@ -42,7 +42,7 @@ export declare const METADATA_KEYS: {
     /** Per-method request/response event metadata for a typed streaming endpoint. */
     STREAM_ENDPOINTS: string;
     /** Per-method MCP-user authorization, intentionally separate from HTTP hop auth. */
-    MCP_AUTH_JWT: string;
+    LOCAL_ONLY: string;
     /** Per-method explicit path/query parameter declarations, keyed by parameter index. */
     HTTP_PARAMETERS: string;
 };
@@ -81,109 +81,11 @@ export declare function getMaskSpec(apiClass: Function, methodName: string): Mas
  * The non-empty reason makes anonymous exposure an explicit review decision.
  */
 export declare function WpAuthPublic(reason: string): MethodDecorator;
-/**
- * @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
- * @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: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /
- * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.
- */
-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
- * whose two plausible answers is how the widest grant kept hiding behind an absent field.
- */
-export declare function rolesRequired(requirement: JwtRequirement): readonly string[];
-/**
- * @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 (`@WpAuthOidc('svc-a')`) only when you want
- * an additional app-level allow-list as defense-in-depth.
- */
-export declare function WpAuthOidc(...callers: string[]): MethodDecorator;
-/**
- * @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 WpAuthSharedSecret(key: string): MethodDecorator;
-/**
- * @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 `@WpAuthPublic` was the only reachable posture
- * and `calledBy: 'sentry'` stayed a claim rather than a fact.
- *
- * ```typescript
- * @WpAuthWebhook('sentry')
- * @Endpoint(POST, '/hook/sentry/issue', WRITE, 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
- * `@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.
- *
- * THE FRAMEWORK IMPLEMENTS NO VENDOR CRYPTO, deliberately. Every vendor ships an official validator
- * (`twilio.validateRequest`, `stripe.webhooks.constructEvent`, `@octokit/webhooks-methods`) and every
- * vendor revises its scheme (Twilio added `bodySHA256` for JSON bodies; Stripe versions its header).
- * Reimplementing five of those is signing up to track five security changelogs forever and to be
- * wrong at the moment being wrong matters. The framework hands the hook enough of the raw request to
- * 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 `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.
- * Silently allowing an unverified webhook is the one default that must not exist.
- */
-export declare function WpAuthWebhook(name: string): MethodDecorator;
-/**
- * Declares a customer-held API-key regime and its non-empty ordered credential locations. The app's
- * `ApiKeyHook` validates the whole request and supplies trusted context; the declaration only drives
- * contract/spec metadata. Unlike shared-secret auth, partner callers cannot assert trusted context.
- * Missing hooks fail closed with 401.
- */
-export declare function WpAuthApiKey(regime: string, credentials: ApiKeyCredentials): MethodDecorator;
-/**
- * @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
- * @WpAuthLocalOnly()
- * @Endpoint(POST, '/logs', WRITE, RPC)
- * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }
- * ```
- *
- * WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in
- * sync by a comment: a route module that registered the route only locally, PLUS a
- * `if (env !== 'local') throw new ApiForbiddenError(...)` 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 `@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 @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.
- *
- * HOW "local" IS DECIDED: {@link RuntimeLocality}, declared once at startup (a REQUIRED input to
- * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint
- * rather than exposing it.
- */
-export declare function WpAuthLocalOnly(): MethodDecorator;
+/** Protected network ingress: authenticate one declared credential, then authorize independently. */
+export declare function WpAuth(methods: AuthMethods): MethodDecorator;
+/** Locality is independent of authentication and cannot prove a user or machine identity. */
+export declare function WpLocalOnly(): MethodDecorator;
+export declare function isLocalOnly(apiClass: Function, methodName: string): boolean;
 /**
  * Get the base path from @ApiPath decorator.
  */
@@ -229,20 +131,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 WpAuthWebhook} hook to verify.
+ * verbatim bytes + absolute url for an {@link WebhookAuthCallback} hook to verify.
  */
 export declare function isRawBody(apiClass: Function, methodName: string): boolean;
 /**
- * Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the
+ * Fail-fast at wiring time when an `webhook(...)` 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 (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say
+ * decorators (`webhook(...)` and `@Endpoint`), and no union over one decorator's argument can say
  * anything about the other's.
  *
- * @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.
+ * @throws Error naming the first `webhook(...)` endpoint missing `{ rawBody: true }`.
  */
 export declare function assertEveryWebhookEndpointRetainsRawBody(apiClass: Function): void;
 /**
@@ -253,11 +155,6 @@ export declare function isApiPath(apiClass: Function): boolean;
  * Get method-level auth metadata. Class-level authorization is forbidden.
  */
 export declare function getAuthMeta(apiClass: Function, methodName: string): AuthMeta | 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;
 /**
  * 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.

package/src/http/decorators.js

@@ -6,13 +6,9 @@ exports.Endpoint = Endpoint;
 exports.MaskLog = MaskLog;
 exports.getMaskSpec = getMaskSpec;
 exports.WpAuthPublic = WpAuthPublic;
-exports.WpAuthJwt = WpAuthJwt;
-exports.rolesRequired = rolesRequired;
-exports.WpAuthOidc = WpAuthOidc;
-exports.WpAuthSharedSecret = WpAuthSharedSecret;
-exports.WpAuthWebhook = WpAuthWebhook;
-exports.WpAuthApiKey = WpAuthApiKey;
-exports.WpAuthLocalOnly = WpAuthLocalOnly;
+exports.WpAuth = WpAuth;
+exports.WpLocalOnly = WpLocalOnly;
+exports.isLocalOnly = isLocalOnly;
 exports.getApiPath = getApiPath;
 exports.getEndpoints = getEndpoints;
 exports.getEndpointKinds = getEndpointKinds;
@@ -26,7 +22,6 @@ exports.isRawBody = isRawBody;
 exports.assertEveryWebhookEndpointRetainsRawBody = assertEveryWebhookEndpointRetainsRawBody;
 exports.isApiPath = isApiPath;
 exports.getAuthMeta = getAuthMeta;
-exports.getAuthMode = getAuthMode;
 exports.assertEveryEndpointHasAuthMode = assertEveryEndpointHasAuthMode;
 exports.validateNoConflictingDecorators = validateNoConflictingDecorators;
 require("reflect-metadata");
@@ -36,6 +31,7 @@ const external_caller_1 = require("./external-caller");
 const auth_mode_1 = require("./auth-mode");
 const HttpEndpointOptions_1 = require("./HttpEndpointOptions");
 const HttpContract_1 = require("./HttpContract");
+const authorization_1 = require("./authorization");
 const http_parameter_decorators_1 = require("./http-parameter-decorators");
 var HttpEndpointOptions_2 = require("./HttpEndpointOptions");
 Object.defineProperty(exports, "READ", { enumerable: true, get: function () { return HttpEndpointOptions_2.READ; } });
@@ -81,7 +77,7 @@ exports.METADATA_KEYS = {
     /** Per-method request/response event metadata for a typed streaming endpoint. */
     STREAM_ENDPOINTS: 'webpieces:stream-endpoints',
     /** Per-method MCP-user authorization, intentionally separate from HTTP hop auth. */
-    MCP_AUTH_JWT: 'webpieces:mcp-auth-jwt',
+    LOCAL_ONLY: 'webpieces:local-only',
     /** Per-method explicit path/query parameter declarations, keyed by parameter index. */
     HTTP_PARAMETERS: http_parameter_decorators_1.HTTP_PARAMETERS_METADATA_KEY,
 };
@@ -184,8 +180,7 @@ function getMaskSpec(apiClass, methodName) {
  * method-only: a class-level default is too easy to miss when reviewing one endpoint.
  */
 // webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function defineAuthMode(mode) {
-    const authMeta = new auth_mode_1.AuthMeta(mode);
+function defineAuthMetadata(authMeta) {
     // webpieces-disable no-any-unknown -- reflect-metadata decorator API requires any
     return (target, propertyKey, _descriptor) => {
         if (propertyKey === undefined) {
@@ -211,131 +206,25 @@ function WpAuthPublic(reason) {
     if (typeof reason !== 'string' || reason.trim() === '') {
         throw new Error('@WpAuthPublic requires a non-empty reason explaining why anonymous access is required.');
     }
-    return defineAuthMode({ kind: 'public' });
-}
-/**
- * @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
- * @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: `@WpAuthPublic` / `@WpAuthJwt` / `@WpAuthOidc` /
- * `@WpAuthSharedSecret` / `@WpAuthLocalOnly`.
- */
-// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function WpAuthJwt(requirement) {
-    return defineAuthMode({ kind: 'jwt', requirement });
-}
-/**
- * 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
- * whose two plausible answers is how the widest grant kept hiding behind an absent field.
- */
-// webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of getAuthMode
-function rolesRequired(requirement) {
-    return requirement.allRolesAllowed === true ? [] : requirement.roles;
-}
-/**
- * @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 (`@WpAuthOidc('svc-a')`) only when you want
- * an additional app-level allow-list as defense-in-depth.
- */
-// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function WpAuthOidc(...callers) {
-    return defineAuthMode({ kind: 'oidc', callers });
-}
-/**
- * @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.
- */
-// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function WpAuthSharedSecret(key) {
-    return defineAuthMode({ kind: 'shared-secret', secretKey: key });
-}
-/**
- * @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 `@WpAuthPublic` was the only reachable posture
- * and `calledBy: 'sentry'` stayed a claim rather than a fact.
- *
- * ```typescript
- * @WpAuthWebhook('sentry')
- * @Endpoint(POST, '/hook/sentry/issue', WRITE, 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
- * `@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.
- *
- * THE FRAMEWORK IMPLEMENTS NO VENDOR CRYPTO, deliberately. Every vendor ships an official validator
- * (`twilio.validateRequest`, `stripe.webhooks.constructEvent`, `@octokit/webhooks-methods`) and every
- * vendor revises its scheme (Twilio added `bodySHA256` for JSON bodies; Stripe versions its header).
- * Reimplementing five of those is signing up to track five security changelogs forever and to be
- * wrong at the moment being wrong matters. The framework hands the hook enough of the raw request to
- * 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 `@WpAuthWebhook` endpoint 401s, matching `JwtHook`.
- * Silently allowing an unverified webhook is the one default that must not exist.
- */
-// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function WpAuthWebhook(name) {
-    return defineAuthMode({ kind: 'webhook', name });
+    return defineAuthMetadata(new auth_mode_1.AuthMeta([{ kind: 'public' }], reason));
+}
+/** Protected network ingress: authenticate one declared credential, then authorize independently. */
+// webpieces-disable no-function-outside-class -- canonical method decorator factory
+function WpAuth(methods) {
+    return defineAuthMetadata(new auth_mode_1.AuthMeta(methods, undefined));
+}
+/** Locality is independent of authentication and cannot prove a user or machine identity. */
+// webpieces-disable no-function-outside-class -- canonical method decorator factory
+function WpLocalOnly() {
+    return (target, methodName) => {
+        if (methodName === undefined)
+            throw new Error('@WpLocalOnly is method-only.');
+        Reflect.defineMetadata(exports.METADATA_KEYS.LOCAL_ONLY, true, target.constructor, methodName);
+    };
 }
-/**
- * Declares a customer-held API-key regime and its non-empty ordered credential locations. The app's
- * `ApiKeyHook` validates the whole request and supplies trusted context; the declaration only drives
- * contract/spec metadata. Unlike shared-secret auth, partner callers cannot assert trusted context.
- * Missing hooks fail closed with 401.
- */
-// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function WpAuthApiKey(regime, credentials) {
-    return defineAuthMode({ kind: 'apikey', regime, credentials });
-}
-/**
- * @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
- * @WpAuthLocalOnly()
- * @Endpoint(POST, '/logs', WRITE, RPC)
- * sendBatch(request: SendLogBatchRequest): Promise<SendLogBatchResponse> { ... }
- * ```
- *
- * WHY IT IS AN AUTH MODE AND NOT A ROUTE-MODULE `if`. Apps hand-rolled this in TWO places kept in
- * sync by a comment: a route module that registered the route only locally, PLUS a
- * `if (env !== 'local') throw new ApiForbiddenError(...)` 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 `@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 @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.
- *
- * HOW "local" IS DECIDED: {@link RuntimeLocality}, declared once at startup (a REQUIRED input to
- * `RuntimeSetupOptions`). Undeclared means DEPLOYED, so a forgotten wiring call refuses the endpoint
- * rather than exposing it.
- */
-// webpieces-disable no-function-outside-class -- decorator factory; decorators are inherently module-scope
-function WpAuthLocalOnly() {
-    return defineAuthMode({ kind: 'local-only' });
+// webpieces-disable no-function-outside-class -- canonical metadata reader
+function isLocalOnly(apiClass, methodName) {
+    return Reflect.getMetadata(exports.METADATA_KEYS.LOCAL_ONLY, apiClass, methodName) === true;
 }
 // ============================================================
 // Helper functions
@@ -452,32 +341,32 @@ function isFormPost(apiClass, methodName) {
 }
 /**
  * True when the method's @Endpoint declared `{ rawBody: true }` — the transport must retain the
- * verbatim bytes + absolute url for an {@link WpAuthWebhook} hook to verify.
+ * verbatim bytes + absolute url for an {@link WebhookAuthCallback} hook to verify.
  */
 // webpieces-disable no-function-outside-class -- reflect-metadata reader, sibling of isFormPost
 function isRawBody(apiClass, methodName) {
     return getEndpointOptions(apiClass, methodName).rawBody === true;
 }
 /**
- * Fail-fast at wiring time when an `@WpAuthWebhook` endpoint did not ask the transport to keep the
+ * Fail-fast at wiring time when an `webhook(...)` 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 (`@WpAuthWebhook` and `@Endpoint`), and no union over one decorator's argument can say
+ * decorators (`webhook(...)` and `@Endpoint`), and no union over one decorator's argument can say
  * anything about the other's.
  *
- * @throws Error naming the first `@WpAuthWebhook` endpoint missing `{ rawBody: true }`.
+ * @throws Error naming the first `webhook(...)` endpoint missing `{ rawBody: true }`.
  */
 // webpieces-disable no-function-outside-class -- wiring-time assert, sibling of assertEveryEndpointHasAuthMode
 function assertEveryWebhookEndpointRetainsRawBody(apiClass) {
     const endpoints = getEndpoints(apiClass) || {};
     for (const methodName of Object.keys(endpoints)) {
-        if (getAuthMode(apiClass, methodName)?.kind !== 'webhook' ||
+        if (!getAuthMeta(apiClass, methodName)?.methods.some((method) => method.kind === 'webhook') ||
             isRawBody(apiClass, methodName))
             continue;
-        throw new Error(`Endpoint '${methodName}' in ${apiClass.name || 'Unknown'} is @WpAuthWebhook but its @Endpoint ` +
+        throw new Error(`Endpoint '${methodName}' in ${apiClass.name || 'Unknown'} is webhook(...) but its @Endpoint ` +
             `does not declare { rawBody: true }. A webhook hook verifies a signature over the bytes and ` +
             `the url the SENDER transmitted, and without that option the transport parses the body and ` +
             `throws them away — leaving the hook nothing to check.`);
@@ -496,14 +385,6 @@ function isApiPath(apiClass) {
 function getAuthMeta(apiClass, methodName) {
     return Reflect.getMetadata(exports.METADATA_KEYS.AUTH_META, apiClass, methodName);
 }
-/**
- * Get the auth mode for a method, or undefined.
- * Convenience wrapper over getAuthMeta for callers that only want the mode.
- */
-// webpieces-disable no-function-outside-class -- typed convenience reader over getAuthMeta
-function getAuthMode(apiClass, methodName) {
-    return getAuthMeta(apiClass, methodName)?.mode;
-}
 /**
  * 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.
@@ -511,11 +392,8 @@ function getAuthMode(apiClass, methodName) {
  * the caller hits becomes the API they believe exists. It leads with the ROLE-GATED member on purpose —
  * the first thing offered should not be the widest grant.
  */
-exports.MISSING_AUTH_DECORATOR_FIX = "Add one of @WpAuthJwt({roles: ['admin']}) / @WpAuthJwt({allRolesAllowed: true}) / " +
-    '@WpAuthOidc(...callers) / @WpAuthSharedSecret(key) / ' +
-    "@WpAuthWebhook('vendor') / @WpAuthApiKey('regime', [{in: 'header', name: 'x-api-key'}]) / " +
-    "@WpAuthLocalOnly() / @WpAuthPublic('why anonymous access is required') to " +
-    'the method.';
+exports.MISSING_AUTH_DECORATOR_FIX = "Declare @WpAuth([jwt(), oidc(...callers), sharedSecret(key), webhook(name), apiKey('regime', [{in: 'header', name: 'x-api-key'}])]) " +
+    "or @WpAuthPublic('reason'), and exactly one @WpAuthorization on every endpoint. Add @WpLocalOnly() separately when locality is required.";
 /**
  * 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
@@ -530,6 +408,20 @@ function assertEveryEndpointHasAuthMode(apiClass) {
             throw new Error(`Endpoint '${methodName}' in ${apiName} has no auth decorator. ` +
                 exports.MISSING_AUTH_DECORATOR_FIX);
         }
+        const policy = (0, authorization_1.getAuthorization)(apiClass, methodName);
+        if (!policy)
+            throw new Error(`Endpoint '${methodName}' in ${apiName} requires @WpAuthorization.`);
+        authorization_1.AuthorizationDeclaration.validate(policy);
+        const auth = getAuthMeta(apiClass, methodName);
+        const isPublic = auth.methods.some((method) => method.kind === 'public');
+        if (isPublic !== (policy.authType === authorization_1.AuthorizationType.ANONYMOUS)) {
+            throw new Error(`Endpoint '${methodName}' must pair public authentication with ANONYMOUS authorization, or protected authentication with protected/CUSTOM authorization.`);
+        }
+    }
+    const policyMethods = Reflect.getMetadata(authorization_1.AUTHORIZATION_METHODS_KEY, apiClass) ?? [];
+    for (const methodName of policyMethods) {
+        if (!(methodName in endpoints))
+            throw new Error(`Orphan @WpAuthorization on ${apiName}.${methodName}; declare @Endpoint.`);
     }
 }
 /**
@@ -547,9 +439,7 @@ function validateNoConflictingDecorators(apiClass, methodName) {
             ? `method '${methodName}' of ${targetName}`
             : `class ${targetName}`;
         throw new Error(`Conflicting auth decorator on ${location}. ` +
-            `Only one of @WpAuthJwt({...}) / @WpAuthOidc(...) / @WpAuthSharedSecret(...) / ` +
-            `@WpAuthWebhook(...) / @WpAuthApiKey(...) / @WpAuthLocalOnly() / ` +
-            `@WpAuthPublic('reason') is allowed per target.`);
+            `Exactly one @WpAuth([...]) or @WpAuthPublic('reason') is allowed per endpoint.`);
     }
 }
 //# sourceMappingURL=decorators.js.map