@webpieces/core-util 0.4.863 → 0.4.865

package/src/http/WpAuthJwtCompileAssertions.d.ts

@@ -1,31 +1,5 @@
-/**
- * COMPILE-TIME assertions for `JwtRoles` — the guarantee that every broken role decision is a compile
- * error rather than a silent over-permissioning. Each `@ts-expect-error` below FAILS THE BUILD (TS2578,
- * "unused '@ts-expect-error' directive") if the line it guards ever starts compiling. Verified by
- * deliberately making a guarded line valid and watching `tsc -p tsconfig.lib.json` go red.
- *
- * WHY THIS IS NOT A `.spec.ts` FILE. It was, and it proved nothing: tsconfig.lib.json EXCLUDES spec
- * files, and vitest transpiles with esbuild, which strips types without checking them. So a
- * `@ts-expect-error` in a spec is inert — the suite passes whether or not the guarded line really
- * errors. Verified the hard way: with one guarded line deliberately made VALID, both `vitest run` and
- * `nx run core-util:ci` stayed green. A type-level guarantee must be asserted in a file the
- * type-checker actually compiles, which is any non-spec file under `src/`.
- *
- * WHY IT CALLS THE FACTORIES INSTEAD OF USING DECORATOR SYNTAX. A decorator factory is a plain
- * function, so a direct call type-checks the argument identically — and the first cut of this file,
- * which used `@ApiPath` + `@Endpoint` on an abstract class, made the architecture scanner classify
- * core-util as exporting an API contract and demand a `role:api-lib` tag. A test fixture must not
- * change what the repo believes about its own architecture.
- *
- * The counterpart RUNTIME behaviour (that `allRolesAllowed: true` reads back as `[]` through
- * `rolesRequired`) is asserted in `__tests__/pubsub-and-auth-decorators.spec.ts`, where runtime
- * assertions belong.
- */
+/** Type assertions run in the library build because vitest erases types. */
 export declare class AuthJwtCompileAssertions {
-    /** The two legitimate spellings must keep compiling; this half is asserted by the ABSENCE of error. */
     legitimate(): void;
-    /** Every one of these must be UNWRITABLE. A directive going unused here fails the build. */
     rejected(): void;
-    /** Class-level auth readers were deleted; every metadata lookup must name the audited method. */
-    readersRequireMethodName(): void;
 }

package/src/http/WpAuthJwtCompileAssertions.js

@@ -2,59 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthJwtCompileAssertions = void 0;
 const decorators_1 = require("./decorators");
-/**
- * COMPILE-TIME assertions for `JwtRoles` — the guarantee that every broken role decision is a compile
- * error rather than a silent over-permissioning. Each `@ts-expect-error` below FAILS THE BUILD (TS2578,
- * "unused '@ts-expect-error' directive") if the line it guards ever starts compiling. Verified by
- * deliberately making a guarded line valid and watching `tsc -p tsconfig.lib.json` go red.
- *
- * WHY THIS IS NOT A `.spec.ts` FILE. It was, and it proved nothing: tsconfig.lib.json EXCLUDES spec
- * files, and vitest transpiles with esbuild, which strips types without checking them. So a
- * `@ts-expect-error` in a spec is inert — the suite passes whether or not the guarded line really
- * errors. Verified the hard way: with one guarded line deliberately made VALID, both `vitest run` and
- * `nx run core-util:ci` stayed green. A type-level guarantee must be asserted in a file the
- * type-checker actually compiles, which is any non-spec file under `src/`.
- *
- * WHY IT CALLS THE FACTORIES INSTEAD OF USING DECORATOR SYNTAX. A decorator factory is a plain
- * function, so a direct call type-checks the argument identically — and the first cut of this file,
- * which used `@ApiPath` + `@Endpoint` on an abstract class, made the architecture scanner classify
- * core-util as exporting an API contract and demand a `role:api-lib` tag. A test fixture must not
- * change what the repo believes about its own architecture.
- *
- * The counterpart RUNTIME behaviour (that `allRolesAllowed: true` reads back as `[]` through
- * `rolesRequired`) is asserted in `__tests__/pubsub-and-auth-decorators.spec.ts`, where runtime
- * assertions belong.
- */
+const auth_mode_1 = require("./auth-mode");
+// @ts-expect-error standalone JWT declarations are removed; use WpAuth([jwt()]) plus WpAuthorization
+const decorators_2 = require("./decorators");
+/** Type assertions run in the library build because vitest erases types. */
 class AuthJwtCompileAssertions {
-    /** The two legitimate spellings must keep compiling; this half is asserted by the ABSENCE of error. */
     legitimate() {
-        void (0, decorators_1.WpAuthJwt)({ roles: ['admin'] });
-        void (0, decorators_1.WpAuthJwt)({ roles: ['admin', 'editor'] });
-        void (0, decorators_1.WpAuthJwt)({ allRolesAllowed: true });
-        void (0, decorators_1.WpAuthJwt)({ allRolesAllowed: true, inOrg: true });
-        void (0, decorators_1.WpAuthJwt)({ roles: ['admin'], tenantScoped: true });
+        void (0, decorators_1.WpAuth)([(0, auth_mode_1.jwt)()]);
     }
-    /** Every one of these must be UNWRITABLE. A directive going unused here fails the build. */
     rejected() {
-        // @ts-expect-error pick a branch — {} may not mean "any authenticated user"
-        void (0, decorators_1.WpAuthJwt)({});
-        // @ts-expect-error roles needs AT LEAST ONE entry; [] was the old silent widest grant
-        void (0, decorators_1.WpAuthJwt)({ roles: [] });
-        // @ts-expect-error contradictory: wide AND role-gated at the same time
-        void (0, decorators_1.WpAuthJwt)({ allRolesAllowed: true, roles: ['admin'] });
-        // @ts-expect-error allRolesAllowed:false is a redundant SECOND spelling of role-gating
-        void (0, decorators_1.WpAuthJwt)({ roles: ['admin'], allRolesAllowed: false });
-        // @ts-expect-error `false` is never how you say "wide" — the other branch is for that
-        void (0, decorators_1.WpAuthJwt)({ allRolesAllowed: false });
-        // @ts-expect-error app-defined fields alone authorize nothing; a role decision is mandatory
-        void (0, decorators_1.WpAuthJwt)({ inOrg: true });
-    }
-    /** Class-level auth readers were deleted; every metadata lookup must name the audited method. */
-    readersRequireMethodName() {
-        // @ts-expect-error methodName is mandatory so removed class-level auth cannot silently compile
+        // @ts-expect-error a protected declaration requires at least one credential descriptor
+        void (0, decorators_1.WpAuth)([]);
+        // @ts-expect-error policy belongs on WpAuthorization
+        void (0, auth_mode_1.jwt)({ roles: ['admin'] });
+        // @ts-expect-error method metadata cannot be read without the method name
         void (0, decorators_1.getAuthMeta)(AuthJwtCompileAssertions);
-        // @ts-expect-error methodName is mandatory so removed class-level auth cannot silently compile
-        void (0, decorators_1.getAuthMode)(AuthJwtCompileAssertions);
+        void decorators_2.WpAuthJwt;
+        void decorators_2.getAuthMode;
+        void decorators_2.rolesRequired;
     }
 }
 exports.AuthJwtCompileAssertions = AuthJwtCompileAssertions;

package/src/http/WpAuthJwtCompileAssertions.js.map

@@ -1 +1 @@
-{"version":3,"file":"WpAuthJwtCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WpAuthJwtCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,6CAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,wBAAwB;IACjC,uGAAuG;IACvG,UAAU;QACN,KAAK,IAAA,sBAAS,EAAC,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrC,KAAK,IAAA,sBAAS,EAAC,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC/C,KAAK,IAAA,sBAAS,EAAC,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,KAAK,IAAA,sBAAS,EAAC,EAAE,eAAe,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,KAAK,IAAA,sBAAS,EAAC,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,4FAA4F;IAC5F,QAAQ;QACJ,4EAA4E;QAC5E,KAAK,IAAA,sBAAS,EAAC,EAAE,CAAC,CAAC;QACnB,sFAAsF;QACtF,KAAK,IAAA,sBAAS,EAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAC9B,uEAAuE;QACvE,KAAK,IAAA,sBAAS,EAAC,EAAE,eAAe,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5D,uFAAuF;QACvF,KAAK,IAAA,sBAAS,EAAC,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7D,sFAAsF;QACtF,KAAK,IAAA,sBAAS,EAAC,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3C,4FAA4F;QAC5F,KAAK,IAAA,sBAAS,EAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,iGAAiG;IACjG,wBAAwB;QACpB,+FAA+F;QAC/F,KAAK,IAAA,wBAAW,EAAC,wBAAwB,CAAC,CAAC;QAC3C,+FAA+F;QAC/F,KAAK,IAAA,wBAAW,EAAC,wBAAwB,CAAC,CAAC;IAC/C,CAAC;CACJ;AAjCD,4DAiCC","sourcesContent":["import { getAuthMeta, getAuthMode, WpAuthJwt } from './decorators';\n\n/**\n * COMPILE-TIME assertions for `JwtRoles` — the guarantee that every broken role decision is a compile\n * error rather than a silent over-permissioning. Each `@ts-expect-error` below FAILS THE BUILD (TS2578,\n * \"unused '@ts-expect-error' directive\") if the line it guards ever starts compiling. Verified by\n * deliberately making a guarded line valid and watching `tsc -p tsconfig.lib.json` go red.\n *\n * WHY THIS IS NOT A `.spec.ts` FILE. It was, and it proved nothing: tsconfig.lib.json EXCLUDES spec\n * files, and vitest transpiles with esbuild, which strips types without checking them. So a\n * `@ts-expect-error` in a spec is inert — the suite passes whether or not the guarded line really\n * errors. Verified the hard way: with one guarded line deliberately made VALID, both `vitest run` and\n * `nx run core-util:ci` stayed green. A type-level guarantee must be asserted in a file the\n * type-checker actually compiles, which is any non-spec file under `src/`.\n *\n * WHY IT CALLS THE FACTORIES INSTEAD OF USING DECORATOR SYNTAX. A decorator factory is a plain\n * function, so a direct call type-checks the argument identically — and the first cut of this file,\n * which used `@ApiPath` + `@Endpoint` on an abstract class, made the architecture scanner classify\n * core-util as exporting an API contract and demand a `role:api-lib` tag. A test fixture must not\n * change what the repo believes about its own architecture.\n *\n * The counterpart RUNTIME behaviour (that `allRolesAllowed: true` reads back as `[]` through\n * `rolesRequired`) is asserted in `__tests__/pubsub-and-auth-decorators.spec.ts`, where runtime\n * assertions belong.\n */\nexport class AuthJwtCompileAssertions {\n    /** The two legitimate spellings must keep compiling; this half is asserted by the ABSENCE of error. */\n    legitimate(): void {\n        void WpAuthJwt({ roles: ['admin'] });\n        void WpAuthJwt({ roles: ['admin', 'editor'] });\n        void WpAuthJwt({ allRolesAllowed: true });\n        void WpAuthJwt({ allRolesAllowed: true, inOrg: true });\n        void WpAuthJwt({ roles: ['admin'], tenantScoped: true });\n    }\n\n    /** Every one of these must be UNWRITABLE. A directive going unused here fails the build. */\n    rejected(): void {\n        // @ts-expect-error pick a branch — {} may not mean \"any authenticated user\"\n        void WpAuthJwt({});\n        // @ts-expect-error roles needs AT LEAST ONE entry; [] was the old silent widest grant\n        void WpAuthJwt({ roles: [] });\n        // @ts-expect-error contradictory: wide AND role-gated at the same time\n        void WpAuthJwt({ allRolesAllowed: true, roles: ['admin'] });\n        // @ts-expect-error allRolesAllowed:false is a redundant SECOND spelling of role-gating\n        void WpAuthJwt({ roles: ['admin'], allRolesAllowed: false });\n        // @ts-expect-error `false` is never how you say \"wide\" — the other branch is for that\n        void WpAuthJwt({ allRolesAllowed: false });\n        // @ts-expect-error app-defined fields alone authorize nothing; a role decision is mandatory\n        void WpAuthJwt({ inOrg: true });\n    }\n\n    /** Class-level auth readers were deleted; every metadata lookup must name the audited method. */\n    readersRequireMethodName(): void {\n        // @ts-expect-error methodName is mandatory so removed class-level auth cannot silently compile\n        void getAuthMeta(AuthJwtCompileAssertions);\n        // @ts-expect-error methodName is mandatory so removed class-level auth cannot silently compile\n        void getAuthMode(AuthJwtCompileAssertions);\n    }\n}\n"]}
+{"version":3,"file":"WpAuthJwtCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WpAuthJwtCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,6CAAmD;AACnD,2CAAkC;AAClC,qGAAqG;AACrG,6CAAqE;AAErE,4EAA4E;AAC5E,MAAa,wBAAwB;IACjC,UAAU;QACN,KAAK,IAAA,mBAAM,EAAC,CAAC,IAAA,eAAG,GAAE,CAAC,CAAC,CAAC;IACzB,CAAC;IAED,QAAQ;QACJ,uFAAuF;QACvF,KAAK,IAAA,mBAAM,EAAC,EAAE,CAAC,CAAC;QAChB,qDAAqD;QACrD,KAAK,IAAA,eAAG,EAAC,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/B,0EAA0E;QAC1E,KAAK,IAAA,wBAAW,EAAC,wBAAwB,CAAC,CAAC;QAC3C,KAAK,sBAAS,CAAC;QACf,KAAK,wBAAW,CAAC;QACjB,KAAK,0BAAa,CAAC;IACvB,CAAC;CACJ;AAhBD,4DAgBC","sourcesContent":["import { getAuthMeta, WpAuth } from './decorators';\nimport { jwt } from './auth-mode';\n// @ts-expect-error standalone JWT declarations are removed; use WpAuth([jwt()]) plus WpAuthorization\nimport { WpAuthJwt, getAuthMode, rolesRequired } from './decorators';\n\n/** Type assertions run in the library build because vitest erases types. */\nexport class AuthJwtCompileAssertions {\n    legitimate(): void {\n        void WpAuth([jwt()]);\n    }\n\n    rejected(): void {\n        // @ts-expect-error a protected declaration requires at least one credential descriptor\n        void WpAuth([]);\n        // @ts-expect-error policy belongs on WpAuthorization\n        void jwt({ roles: ['admin'] });\n        // @ts-expect-error method metadata cannot be read without the method name\n        void getAuthMeta(AuthJwtCompileAssertions);\n        void WpAuthJwt;\n        void getAuthMode;\n        void rolesRequired;\n    }\n}\n"]}

package/src/http/WpAuthorizationCompileAssertions.d.ts

@@ -0,0 +1 @@
+export {};

package/src/http/WpAuthorizationCompileAssertions.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const authorization_1 = require("./authorization");
+class OrderPolicy {
+    permission;
+}
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ALL_USERS });
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ROLES, roles: ['editor'] });
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.CUSTOM, appPolicy: { permission: 'orders:edit' } });
+// @ts-expect-error ROLES requires a nonempty tuple
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ROLES, roles: [] });
+// @ts-expect-error ROLES requires explicit roles
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ROLES });
+// @ts-expect-error CUSTOM requires typed application policy
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.CUSTOM });
+// @ts-expect-error standard policies reject application policy
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ALL_USERS, appPolicy: { permission: 'orders:edit' } });
+// @ts-expect-error roles are accepted only by ROLES
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.SERVICE_ONLY, roles: ['editor'] });
+// @ts-expect-error arbitrary top-level permissions belong in CUSTOM.appPolicy
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ALL_USERS, permission: 'orders:read' });
+// @ts-expect-error the application payload is checked by its declared type
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.CUSTOM, appPolicy: { permission: 'users:edit' } });
+// @ts-expect-error anonymous access requires a reason
+(0, authorization_1.WpAuthorization)({ authType: authorization_1.AuthorizationType.ANONYMOUS });
+//# sourceMappingURL=WpAuthorizationCompileAssertions.js.map

package/src/http/WpAuthorizationCompileAssertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WpAuthorizationCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WpAuthorizationCompileAssertions.ts"],"names":[],"mappings":";;AAAA,mDAAqE;AAErE,MAAM,WAAW;IACb,UAAU,CAAiC;CAC9C;AAED,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,SAAS,EAAE,CAAC,CAAC;AAC3D,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC1E,IAAA,+BAAe,EAAc,EAAE,QAAQ,EAAE,iCAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;AAC/G,mDAAmD;AACnD,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;AAClE,iDAAiD;AACjD,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,KAAK,EAAE,CAAC,CAAC;AACvD,4DAA4D;AAC5D,IAAA,+BAAe,EAAc,EAAE,QAAQ,EAAE,iCAAiB,CAAC,MAAM,EAAE,CAAC,CAAC;AACrE,+DAA+D;AAC/D,IAAA,+BAAe,EAAc,EAAE,QAAQ,EAAE,iCAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;AAClH,oDAAoD;AACpD,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACjF,8EAA8E;AAC9E,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC;AACtF,2EAA2E;AAC3E,IAAA,+BAAe,EAAc,EAAE,QAAQ,EAAE,iCAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC;AAC9G,sDAAsD;AACtD,IAAA,+BAAe,EAAC,EAAE,QAAQ,EAAE,iCAAiB,CAAC,SAAS,EAAE,CAAC,CAAC","sourcesContent":["import { AuthorizationType, WpAuthorization } from './authorization';\n\nclass OrderPolicy {\n    permission!: 'orders:read' | 'orders:edit';\n}\n\nWpAuthorization({ authType: AuthorizationType.ALL_USERS });\nWpAuthorization({ authType: AuthorizationType.ROLES, roles: ['editor'] });\nWpAuthorization<OrderPolicy>({ authType: AuthorizationType.CUSTOM, appPolicy: { permission: 'orders:edit' } });\n// @ts-expect-error ROLES requires a nonempty tuple\nWpAuthorization({ authType: AuthorizationType.ROLES, roles: [] });\n// @ts-expect-error ROLES requires explicit roles\nWpAuthorization({ authType: AuthorizationType.ROLES });\n// @ts-expect-error CUSTOM requires typed application policy\nWpAuthorization<OrderPolicy>({ authType: AuthorizationType.CUSTOM });\n// @ts-expect-error standard policies reject application policy\nWpAuthorization<OrderPolicy>({ authType: AuthorizationType.ALL_USERS, appPolicy: { permission: 'orders:edit' } });\n// @ts-expect-error roles are accepted only by ROLES\nWpAuthorization({ authType: AuthorizationType.SERVICE_ONLY, roles: ['editor'] });\n// @ts-expect-error arbitrary top-level permissions belong in CUSTOM.appPolicy\nWpAuthorization({ authType: AuthorizationType.ALL_USERS, permission: 'orders:read' });\n// @ts-expect-error the application payload is checked by its declared type\nWpAuthorization<OrderPolicy>({ authType: AuthorizationType.CUSTOM, appPolicy: { permission: 'users:edit' } });\n// @ts-expect-error anonymous access requires a reason\nWpAuthorization({ authType: AuthorizationType.ANONYMOUS });\n"]}

package/src/http/auth-mode.d.ts

@@ -1,79 +1,3 @@
-/**
- * The TYPE layer of the auth surface: what an endpoint's credential posture IS, with no decorator and
- * no reflect-metadata. `decorators.ts` (which attaches these) imports FROM here, never the other way,
- * so a reader that only needs to switch on a mode — `DestinationTrust`, `RouteMetadata`, a spec
- * generator — does not drag the whole decorator surface in with it.
- *
- * Split out of `decorators.ts` purely for file size, exactly as `api-kind.ts`, `external-caller.ts` and
- * `RouteMetadata.ts` were before it. Nothing about these types' role changed in the move, and the
- * barrel keeps the package surface identical.
- */
-/**
- * The role decision for a JWT endpoint, as a union the COMPILER enforces — one spelling per decision,
- * every broken combination a compile error:
- *
- * ```typescript
- * @WpAuthJwt({ roles: ['admin'] })            // ✅ role-gated (any-of)
- * @WpAuthJwt({ allRolesAllowed: true })       // ✅ every authenticated user, said out loud
- * @WpAuthJwt({})                              // ❌ pick a branch
- * @WpAuthJwt({ roles: [] })                   // ❌ needs at least one role
- * ```
- *
- * `allRolesAllowed` exists ONLY on the wide branch (the dangerous half must be a greppable token, and
- * the narrow branch rejects it as a redundant second spelling); `roles` is a NON-EMPTY tuple so
- * "declared roles, passed none" — the old optional `string[]`'s silent widest grant — cannot be written.
- * All six bad cases are pinned in `AuthJwtCompileAssertions.ts` — a COMPILED file, not a spec: tsc
- * fails the build (TS2578) if any starts compiling. A spec cannot do this (see that file's header).
- *
- * WHY a type rather than the runtime `throw` this replaced: `.claude/review/backwards-compatibility.md`
- * shim shapes #4 and #5. Not restated here — three copies of one rationale is three things to drift.
- */
-export type JwtRoles = {
-    allRolesAllowed: true;
-    roles?: never;
-} | {
-    roles: readonly [string, ...string[]];
-    allRolesAllowed?: never;
-};
-/**
- * JwtRequirement - the {@link JwtRoles} decision PLUS any app-defined authorization fields, e.g.
- * `@WpAuthJwt({ allRolesAllowed: true, inOrg: true })`. The framework authenticates (JwtHook.parseJwt)
- * and enforces the roles any-of; the app overrides JwtHook.authorizeJwt to enforce its own fields.
- * Both hook methods are ASYNC, so an app field like `inOrg` may be answered from a datastore.
- *
- * This was a SECOND decorator (`@Auth`) whose `roles` was optional — so `@Auth({})` reached the exact
- * widest grant that {@link JwtRoles} exists to make un-typeable. Folding it in leaves one decorator per
- * credential kind and closes that route by construction.
- */
-export type JwtRequirement = JwtRoles & {
-    [field: string]: unknown;
-};
-/**
- * WHERE ONE api-key credential rides on the wire, as a union the COMPILER enforces — the DECLARATION
- * a spec generator turns into an OpenAPI `securityScheme`:
- *
- * ```typescript
- * { in: 'header', name: 'x-api-key' }   // ✅ → {type: apiKey, in: header, name: x-api-key}
- * { in: 'bearer' }                      // ✅ → {type: http, scheme: bearer}
- * { in: 'bearer', name: 'x-api-key' }   // ❌ bearer's location IS `Authorization`; a name is a lie
- * { in: 'header' }                      // ❌ a header credential with no header name is unusable
- * ```
- *
- * WHY A UNION AND NOT ONE OPTIONAL `headerName`. The two OpenAPI schemes reachable from "an api key"
- * are structurally DIFFERENT documents (`type: apiKey` + `in` + `name` vs `type: http` + `scheme`).
- * A single optional field makes the contradictory combination REPRESENTABLE, and a generator handed
- * `{in: 'bearer', name: 'x-api-key'}` has to either guess or emit a silently-wrong published contract.
- * `name?: never` on the bearer branch is what deletes that state — the same device {@link JwtRoles}
- * uses, pinned the same way in `AuthApiKeyCompileAssertions.ts` (a COMPILED file, not a spec).
- *
- * THIS IS DESCRIPTION, NOT HANDLING. The framework reads no header from this; `ApiKeyHook` still gets
- * the whole request and still owns the cross-check. Declaring the location cannot regress running auth
- * — it exists so the location stops living ONLY in a hand-written spec fragment that drifts silently
- * from the hook's own header constants.
- *
- * `description` is carried because it is what a docs site renders on its authorization card, and that
- * prose belongs beside the declaration rather than in a hand-maintained JSON file.
- */
 export type ApiKeyCredential = {
     in: 'header';
     name: string;
@@ -83,48 +7,13 @@ export type ApiKeyCredential = {
     name?: never;
     description?: string;
 };
-/**
- * EVERY credential one api-key regime requires, in the order they appear in the published document.
- *
- * A NON-EMPTY tuple, for the same reason {@link JwtRoles}'s `roles` is one: a regime that declares no
- * credential would generate a document with no security block — the exact silent failure the
- * declaration exists to remove — so `[]` is a COMPILE error rather than a runtime throw (shim shape
- * #4). More than one entry is the normal case, not an exotic one: a real regime authenticates a PAIR,
- * and every entry here must be presented TOGETHER (an AND, i.e. ONE OpenAPI security-requirement
- * object holding every scheme, never a LIST of one-key objects, which would mean "either suffices").
- */
 export type ApiKeyCredentials = readonly [ApiKeyCredential, ...ApiKeyCredential[]];
-/**
- * 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 JWT; `requirement` carries the compiler-enforced role decision
- *                     ({@link JwtRoles}) plus any app-defined authorization fields
- * - `oidc`          → Google OIDC service-to-service (Cloud Tasks delivery / cross-service RPC);
- *                     `callers` is the allow-list of caller SAs ('self' = this service's SA)
- * - `shared-secret` → constant-time compare of a header against the secret bound for `secretKey`
- * - `webhook`       → an OUTSIDE vendor signed this request its own way; the app's bound `WebhookAuthCallback`
- *                     verifies it, selected by `name`. The framework ships NO vendor crypto (see
- *                     {@link WpAuthWebhook}).
- * - `apikey`        → a CUSTOMER holds the credential; the app's bound `ApiKeyHook` looks it up
- *                     (async, over the whole header set) and returns the context to seed, selected
- *                     by `regime`. `credentials` DECLARES where the credential rides — an ORDERED,
- *                     non-empty list, because a real regime authenticates a PAIR (a key AND the
- *                     organization id it acts for) that must be presented TOGETHER. NOT a peer
- *                     service — see {@link WpAuthApiKey}.
- * - `local-only`    → exists ONLY on a developer's machine; not registered and never served when
- *                     {@link RuntimeLocality} says this process is deployed. Authenticates NOBODY —
- *                     it is a deployment gate, not a credential.
- */
-export type AuthMode = {
-    kind: 'public';
-} | {
+/** One concrete mechanism; user policy belongs exclusively to WpAuthorization. */
+export type AuthMethod = {
     kind: 'jwt';
-    requirement: JwtRequirement;
 } | {
     kind: 'oidc';
-    callers: string[];
+    callers: readonly string[];
 } | {
     kind: 'shared-secret';
     secretKey: string;
@@ -135,22 +24,25 @@ export type AuthMode = {
     kind: 'apikey';
     regime: string;
     credentials: ApiKeyCredentials;
-} | {
-    kind: 'local-only';
 };
-/**
- * Auth metadata attached to a class or method via one of the auth decorators
- * (@WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthWebhook / @WpAuthApiKey / @WpAuthLocalOnly) —
- * one per credential kind.
- *
- * Carries a discriminated {@link AuthMode} and nothing else. It USED to also expose
- * `authenticated`/`roles` getters "for back-compat with readers that only understand the user-JWT
- * model" — deleted, because nothing read them: every reader (AuthFilter, BrowserProxyClient,
- * ProxyClient) switches on `mode.kind`, which is the whole point of the discriminated union. A
- * flattened view of a union is a second spelling of it, and the flattened one silently answers
- * `authenticated: true` for oidc and shared-secret too.
- */
+export type AuthMethods = readonly [AuthMethod, ...AuthMethod[]];
+export type AuthMode = AuthMethod | {
+    kind: 'public';
+};
+/** Alternatives remain unresolved until a concrete mechanism is chosen for this hop. */
 export declare class AuthMeta {
-    mode: AuthMode;
-    constructor(mode: AuthMode);
+    readonly publicReason: string | undefined;
+    readonly methods: readonly [AuthMode, ...AuthMode[]];
+    constructor(methods: readonly [AuthMode, ...AuthMode[]], publicReason: string | undefined);
+    private static snapshot;
+}
+export declare class AuthDeclaration {
+    static validate(meta: AuthMeta): void;
+    private static validateMethod;
+    private static requireText;
 }
+export declare function jwt(): AuthMethod;
+export declare function oidc(...callers: string[]): AuthMethod;
+export declare function sharedSecret(secretKey: string): AuthMethod;
+export declare function webhook(name: string): AuthMethod;
+export declare function apiKey(regime: string, credentials: ApiKeyCredentials): AuthMethod;

package/src/http/auth-mode.js

@@ -1,33 +1,107 @@
 "use strict";
-/**
- * The TYPE layer of the auth surface: what an endpoint's credential posture IS, with no decorator and
- * no reflect-metadata. `decorators.ts` (which attaches these) imports FROM here, never the other way,
- * so a reader that only needs to switch on a mode — `DestinationTrust`, `RouteMetadata`, a spec
- * generator — does not drag the whole decorator surface in with it.
- *
- * Split out of `decorators.ts` purely for file size, exactly as `api-kind.ts`, `external-caller.ts` and
- * `RouteMetadata.ts` were before it. Nothing about these types' role changed in the move, and the
- * barrel keeps the package surface identical.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthMeta = void 0;
-/**
- * Auth metadata attached to a class or method via one of the auth decorators
- * (@WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthWebhook / @WpAuthApiKey / @WpAuthLocalOnly) —
- * one per credential kind.
- *
- * Carries a discriminated {@link AuthMode} and nothing else. It USED to also expose
- * `authenticated`/`roles` getters "for back-compat with readers that only understand the user-JWT
- * model" — deleted, because nothing read them: every reader (AuthFilter, BrowserProxyClient,
- * ProxyClient) switches on `mode.kind`, which is the whole point of the discriminated union. A
- * flattened view of a union is a second spelling of it, and the flattened one silently answers
- * `authenticated: true` for oidc and shared-secret too.
- */
+exports.AuthDeclaration = exports.AuthMeta = void 0;
+exports.jwt = jwt;
+exports.oidc = oidc;
+exports.sharedSecret = sharedSecret;
+exports.webhook = webhook;
+exports.apiKey = apiKey;
+/** Alternatives remain unresolved until a concrete mechanism is chosen for this hop. */
 class AuthMeta {
-    mode;
-    constructor(mode) {
-        this.mode = mode;
+    publicReason;
+    methods;
+    constructor(methods, publicReason) {
+        this.publicReason = publicReason;
+        this.methods = methods;
+        AuthDeclaration.validate(this);
+        this.methods = Object.freeze(methods.map((method) => AuthMeta.snapshot(method)));
+        Object.freeze(this);
+    }
+    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration
+    static snapshot(method) {
+        switch (method.kind) {
+            case 'oidc': return Object.freeze({ ...method, callers: Object.freeze([...method.callers]) });
+            case 'apikey': return Object.freeze({ ...method, credentials: Object.freeze(method.credentials.map((credential) => Object.freeze({ ...credential }))) });
+            default: return Object.freeze({ ...method });
+        }
     }
 }
 exports.AuthMeta = AuthMeta;
+class AuthDeclaration {
+    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration
+    static validate(meta) {
+        if (!Array.isArray(meta.methods) || meta.methods.length === 0)
+            throw new Error('@WpAuth requires a nonempty methods tuple.');
+        const kinds = new Set();
+        for (const method of meta.methods) {
+            if (!method || typeof method !== 'object' || kinds.has(method.kind))
+                throw new Error('@WpAuth rejects duplicate or invalid credential methods.');
+            kinds.add(method.kind);
+            this.validateMethod(method);
+        }
+        if (kinds.has('public')) {
+            if (meta.methods.length !== 1 || typeof meta.publicReason !== 'string' || !meta.publicReason.trim()) {
+                throw new Error('Public auth must be declared separately with @WpAuthPublic(reason).');
+            }
+        }
+        else if (meta.publicReason !== undefined)
+            throw new Error('Protected @WpAuth rejects public reasons.');
+    }
+    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration
+    static validateMethod(method) {
+        let keys;
+        switch (method.kind) {
+            case 'jwt':
+            case 'public':
+                keys = ['kind'];
+                break;
+            case 'oidc':
+                keys = ['kind', 'callers'];
+                if (!Array.isArray(method.callers) || !method.callers.every((caller) => typeof caller === 'string' && caller.trim().length > 0))
+                    throw new Error('oidc(...) requires valid caller names.');
+                break;
+            case 'shared-secret':
+                keys = ['kind', 'secretKey'];
+                this.requireText(method.secretKey, 'sharedSecret');
+                break;
+            case 'webhook':
+                keys = ['kind', 'name'];
+                this.requireText(method.name, 'webhook');
+                break;
+            case 'apikey':
+                keys = ['kind', 'regime', 'credentials'];
+                this.requireText(method.regime, 'apiKey');
+                if (!Array.isArray(method.credentials) || !method.credentials.length)
+                    throw new Error('apiKey(...) requires a nonempty credentials tuple.');
+                for (const credential of method.credentials) {
+                    if (credential.in === 'header')
+                        this.requireText(credential.name, 'apiKey header');
+                    else if (credential.in !== 'bearer' || Object.hasOwn(credential, 'name'))
+                        throw new Error('Invalid API-key credential location.');
+                }
+                break;
+            default: throw new Error('Unknown @WpAuth method; use jwt/oidc/sharedSecret/webhook/apiKey descriptors.');
+        }
+        for (const key of Object.keys(method)) {
+            if (!keys.includes(key))
+                throw new Error(`Auth method rejects '${key}'; operation policy belongs in @WpAuthorization.`);
+        }
+    }
+    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration
+    static requireText(value, label) {
+        if (typeof value !== 'string' || !value.trim())
+            throw new Error(`${label} requires a nonempty name.`);
+    }
+}
+exports.AuthDeclaration = AuthDeclaration;
+// webpieces-disable no-function-outside-class -- canonical credential descriptor factory
+function jwt() { return { kind: 'jwt' }; }
+// webpieces-disable no-function-outside-class -- canonical credential descriptor factory
+function oidc(...callers) { return { kind: 'oidc', callers }; }
+// webpieces-disable no-function-outside-class -- canonical credential descriptor factory
+function sharedSecret(secretKey) { return { kind: 'shared-secret', secretKey }; }
+// webpieces-disable no-function-outside-class -- canonical credential descriptor factory
+function webhook(name) { return { kind: 'webhook', name }; }
+// webpieces-disable no-function-outside-class -- canonical credential descriptor factory
+function apiKey(regime, credentials) { return { kind: 'apikey', regime, credentials }; }
 //# sourceMappingURL=auth-mode.js.map

package/src/http/auth-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-mode.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/auth-mode.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAiHH;;;;;;;;;;;GAWG;AACH,MAAa,QAAQ;IACjB,IAAI,CAAW;IAEf,YAAY,IAAc;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ;AAND,4BAMC","sourcesContent":["/**\n * The TYPE layer of the auth surface: what an endpoint's credential posture IS, with no decorator and\n * no reflect-metadata. `decorators.ts` (which attaches these) imports FROM here, never the other way,\n * so a reader that only needs to switch on a mode — `DestinationTrust`, `RouteMetadata`, a spec\n * generator — does not drag the whole decorator surface in with it.\n *\n * Split out of `decorators.ts` purely for file size, exactly as `api-kind.ts`, `external-caller.ts` and\n * `RouteMetadata.ts` were before it. Nothing about these types' role changed in the move, and the\n * barrel keeps the package surface identical.\n */\n\n/**\n * The role decision for a JWT endpoint, as a union the COMPILER enforces — one spelling per decision,\n * every broken combination a compile error:\n *\n * ```typescript\n * @WpAuthJwt({ roles: ['admin'] })            // ✅ role-gated (any-of)\n * @WpAuthJwt({ allRolesAllowed: true })       // ✅ every authenticated user, said out loud\n * @WpAuthJwt({})                              // ❌ pick a branch\n * @WpAuthJwt({ roles: [] })                   // ❌ needs at least one role\n * ```\n *\n * `allRolesAllowed` exists ONLY on the wide branch (the dangerous half must be a greppable token, and\n * the narrow branch rejects it as a redundant second spelling); `roles` is a NON-EMPTY tuple so\n * \"declared roles, passed none\" — the old optional `string[]`'s silent widest grant — cannot be written.\n * All six bad cases are pinned in `AuthJwtCompileAssertions.ts` — a COMPILED file, not a spec: tsc\n * fails the build (TS2578) if any starts compiling. A spec cannot do this (see that file's header).\n *\n * WHY a type rather than the runtime `throw` this replaced: `.claude/review/backwards-compatibility.md`\n * shim shapes #4 and #5. Not restated here — three copies of one rationale is three things to drift.\n */\nexport type JwtRoles =\n    | { allRolesAllowed: true; roles?: never }\n    | { roles: readonly [string, ...string[]]; allRolesAllowed?: never };\n\n/**\n * JwtRequirement - the {@link JwtRoles} decision PLUS any app-defined authorization fields, e.g.\n * `@WpAuthJwt({ allRolesAllowed: true, inOrg: true })`. The framework authenticates (JwtHook.parseJwt)\n * and enforces the roles any-of; the app overrides JwtHook.authorizeJwt to enforce its own fields.\n * Both hook methods are ASYNC, so an app field like `inOrg` may be answered from a datastore.\n *\n * This was a SECOND decorator (`@Auth`) whose `roles` was optional — so `@Auth({})` reached the exact\n * widest grant that {@link JwtRoles} exists to make un-typeable. Folding it in leaves one decorator per\n * credential kind and closes that route by construction.\n */\n// webpieces-disable no-any-unknown -- app-defined authorization fields (inOrg, tenant, ...)\nexport type JwtRequirement = JwtRoles & { [field: string]: unknown };\n\n/**\n * WHERE ONE api-key credential rides on the wire, as a union the COMPILER enforces — the DECLARATION\n * a spec generator turns into an OpenAPI `securityScheme`:\n *\n * ```typescript\n * { in: 'header', name: 'x-api-key' }   // ✅ → {type: apiKey, in: header, name: x-api-key}\n * { in: 'bearer' }                      // ✅ → {type: http, scheme: bearer}\n * { in: 'bearer', name: 'x-api-key' }   // ❌ bearer's location IS `Authorization`; a name is a lie\n * { in: 'header' }                      // ❌ a header credential with no header name is unusable\n * ```\n *\n * WHY A UNION AND NOT ONE OPTIONAL `headerName`. The two OpenAPI schemes reachable from \"an api key\"\n * are structurally DIFFERENT documents (`type: apiKey` + `in` + `name` vs `type: http` + `scheme`).\n * A single optional field makes the contradictory combination REPRESENTABLE, and a generator handed\n * `{in: 'bearer', name: 'x-api-key'}` has to either guess or emit a silently-wrong published contract.\n * `name?: never` on the bearer branch is what deletes that state — the same device {@link JwtRoles}\n * uses, pinned the same way in `AuthApiKeyCompileAssertions.ts` (a COMPILED file, not a spec).\n *\n * THIS IS DESCRIPTION, NOT HANDLING. The framework reads no header from this; `ApiKeyHook` still gets\n * the whole request and still owns the cross-check. Declaring the location cannot regress running auth\n * — it exists so the location stops living ONLY in a hand-written spec fragment that drifts silently\n * from the hook's own header constants.\n *\n * `description` is carried because it is what a docs site renders on its authorization card, and that\n * prose belongs beside the declaration rather than in a hand-maintained JSON file.\n */\nexport type ApiKeyCredential =\n    | { in: 'header'; name: string; description?: string }\n    | { in: 'bearer'; name?: never; description?: string };\n\n/**\n * EVERY credential one api-key regime requires, in the order they appear in the published document.\n *\n * A NON-EMPTY tuple, for the same reason {@link JwtRoles}'s `roles` is one: a regime that declares no\n * credential would generate a document with no security block — the exact silent failure the\n * declaration exists to remove — so `[]` is a COMPILE error rather than a runtime throw (shim shape\n * #4). More than one entry is the normal case, not an exotic one: a real regime authenticates a PAIR,\n * and every entry here must be presented TOGETHER (an AND, i.e. ONE OpenAPI security-requirement\n * object holding every scheme, never a LIST of one-key objects, which would mean \"either suffices\").\n */\nexport type ApiKeyCredentials = readonly [ApiKeyCredential, ...ApiKeyCredential[]];\n\n/**\n * The service-to-service / user auth mode of an endpoint. Discriminated union so a filter can\n * `switch (mode.kind)` and get the data it needs, exhaustively.\n *\n * - `public`        → no auth check\n * - `jwt`           → user JWT; `requirement` carries the compiler-enforced role decision\n *                     ({@link JwtRoles}) plus any app-defined authorization fields\n * - `oidc`          → Google OIDC service-to-service (Cloud Tasks delivery / cross-service RPC);\n *                     `callers` is the allow-list of caller SAs ('self' = this service's SA)\n * - `shared-secret` → constant-time compare of a header against the secret bound for `secretKey`\n * - `webhook`       → an OUTSIDE vendor signed this request its own way; the app's bound `WebhookAuthCallback`\n *                     verifies it, selected by `name`. The framework ships NO vendor crypto (see\n *                     {@link WpAuthWebhook}).\n * - `apikey`        → a CUSTOMER holds the credential; the app's bound `ApiKeyHook` looks it up\n *                     (async, over the whole header set) and returns the context to seed, selected\n *                     by `regime`. `credentials` DECLARES where the credential rides — an ORDERED,\n *                     non-empty list, because a real regime authenticates a PAIR (a key AND the\n *                     organization id it acts for) that must be presented TOGETHER. NOT a peer\n *                     service — see {@link WpAuthApiKey}.\n * - `local-only`    → exists ONLY on a developer's machine; not registered and never served when\n *                     {@link RuntimeLocality} says this process is deployed. Authenticates NOBODY —\n *                     it is a deployment gate, not a credential.\n */\nexport type AuthMode =\n    | { kind: 'public' }\n    | { kind: 'jwt'; requirement: JwtRequirement }\n    | { kind: 'oidc'; callers: string[] }\n    | { kind: 'shared-secret'; secretKey: string }\n    | { kind: 'webhook'; name: string }\n    | { kind: 'apikey'; regime: string; credentials: ApiKeyCredentials }\n    | { kind: 'local-only' };\n\n/**\n * Auth metadata attached to a class or method via one of the auth decorators\n * (@WpAuthPublic / @WpAuthJwt / @WpAuthOidc / @WpAuthSharedSecret / @WpAuthWebhook / @WpAuthApiKey / @WpAuthLocalOnly) —\n * one per credential kind.\n *\n * Carries a discriminated {@link AuthMode} and nothing else. It USED to also expose\n * `authenticated`/`roles` getters \"for back-compat with readers that only understand the user-JWT\n * model\" — deleted, because nothing read them: every reader (AuthFilter, BrowserProxyClient,\n * ProxyClient) switches on `mode.kind`, which is the whole point of the discriminated union. A\n * flattened view of a union is a second spelling of it, and the flattened one silently answers\n * `authenticated: true` for oidc and shared-secret too.\n */\nexport class AuthMeta {\n    mode: AuthMode;\n\n    constructor(mode: AuthMode) {\n        this.mode = mode;\n    }\n}\n"]}
+{"version":3,"file":"auth-mode.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/auth-mode.ts"],"names":[],"mappings":"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","sourcesContent":["export type ApiKeyCredential =\n    | { in: 'header'; name: string; description?: string }\n    | { in: 'bearer'; name?: never; description?: string };\n\nexport type ApiKeyCredentials = readonly [ApiKeyCredential, ...ApiKeyCredential[]];\n\n/** One concrete mechanism; user policy belongs exclusively to WpAuthorization. */\nexport type AuthMethod =\n    | { kind: 'jwt' }\n    | { kind: 'oidc'; callers: readonly string[] }\n    | { kind: 'shared-secret'; secretKey: string }\n    | { kind: 'webhook'; name: string }\n    | { kind: 'apikey'; regime: string; credentials: ApiKeyCredentials };\n\nexport type AuthMethods = readonly [AuthMethod, ...AuthMethod[]];\nexport type AuthMode = AuthMethod | { kind: 'public' };\n\n/** Alternatives remain unresolved until a concrete mechanism is chosen for this hop. */\nexport class AuthMeta {\n    readonly methods: readonly [AuthMode, ...AuthMode[]];\n\n    constructor(\n        methods: readonly [AuthMode, ...AuthMode[]],\n        public readonly publicReason: string | undefined,\n    ) {\n        this.methods = methods;\n        AuthDeclaration.validate(this);\n        this.methods = Object.freeze(methods.map((method: AuthMode) => AuthMeta.snapshot(method))) as readonly [AuthMode, ...AuthMode[]];\n        Object.freeze(this);\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static snapshot(method: AuthMode): AuthMode {\n        switch (method.kind) {\n            case 'oidc': return Object.freeze({ ...method, callers: Object.freeze([...method.callers]) });\n            case 'apikey': return Object.freeze({ ...method, credentials: Object.freeze(method.credentials.map((credential: ApiKeyCredential) => Object.freeze({ ...credential }))) as ApiKeyCredentials });\n            default: return Object.freeze({ ...method });\n        }\n    }\n}\n\nexport class AuthDeclaration {\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    static validate(meta: AuthMeta): void {\n        if (!Array.isArray(meta.methods) || meta.methods.length === 0) throw new Error('@WpAuth requires a nonempty methods tuple.');\n        const kinds = new Set<string>();\n        for (const method of meta.methods) {\n            if (!method || typeof method !== 'object' || kinds.has(method.kind)) throw new Error('@WpAuth rejects duplicate or invalid credential methods.');\n            kinds.add(method.kind);\n            this.validateMethod(method);\n        }\n        if (kinds.has('public')) {\n            if (meta.methods.length !== 1 || typeof meta.publicReason !== 'string' || !meta.publicReason.trim()) {\n                throw new Error('Public auth must be declared separately with @WpAuthPublic(reason).');\n            }\n        } else if (meta.publicReason !== undefined) throw new Error('Protected @WpAuth rejects public reasons.');\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static validateMethod(method: AuthMode): void {\n        let keys: readonly string[];\n        switch (method.kind) {\n            case 'jwt':\n            case 'public': keys = ['kind']; break;\n            case 'oidc':\n                keys = ['kind', 'callers'];\n                if (!Array.isArray(method.callers) || !method.callers.every((caller: string) => typeof caller === 'string' && caller.trim().length > 0)) throw new Error('oidc(...) requires valid caller names.');\n                break;\n            case 'shared-secret':\n                keys = ['kind', 'secretKey'];\n                this.requireText(method.secretKey, 'sharedSecret'); break;\n            case 'webhook':\n                keys = ['kind', 'name'];\n                this.requireText(method.name, 'webhook'); break;\n            case 'apikey':\n                keys = ['kind', 'regime', 'credentials'];\n                this.requireText(method.regime, 'apiKey');\n                if (!Array.isArray(method.credentials) || !method.credentials.length) throw new Error('apiKey(...) requires a nonempty credentials tuple.');\n                for (const credential of method.credentials) {\n                    if (credential.in === 'header') this.requireText(credential.name, 'apiKey header');\n                    else if (credential.in !== 'bearer' || Object.hasOwn(credential, 'name')) throw new Error('Invalid API-key credential location.');\n                }\n                break;\n            default: throw new Error('Unknown @WpAuth method; use jwt/oidc/sharedSecret/webhook/apiKey descriptors.');\n        }\n        for (const key of Object.keys(method)) {\n            if (!keys.includes(key)) throw new Error(`Auth method rejects '${key}'; operation policy belongs in @WpAuthorization.`);\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- stateless contract validation or scope metadata reader used before DI registration\n    private static requireText(value: string, label: string): void {\n        if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} requires a nonempty name.`);\n    }\n}\n\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function jwt(): AuthMethod { return { kind: 'jwt' }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function oidc(...callers: string[]): AuthMethod { return { kind: 'oidc', callers }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function sharedSecret(secretKey: string): AuthMethod { return { kind: 'shared-secret', secretKey }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function webhook(name: string): AuthMethod { return { kind: 'webhook', name }; }\n// webpieces-disable no-function-outside-class -- canonical credential descriptor factory\nexport function apiKey(regime: string, credentials: ApiKeyCredentials): AuthMethod { return { kind: 'apikey', regime, credentials }; }\n"]}

package/src/http/authorization.d.ts

@@ -0,0 +1,38 @@
+import 'reflect-metadata';
+export declare enum AuthorizationType {
+    ALL_USERS = "all-users",
+    ROLES = "roles",
+    SERVICE_ONLY = "service-only",
+    USERS_OR_SERVICES = "users-or-services",
+    ANONYMOUS = "anonymous",
+    CUSTOM = "custom"
+}
+export type AuthorizationRequirement<TPolicy = never> = {
+    authType: AuthorizationType.ALL_USERS | AuthorizationType.SERVICE_ONLY | AuthorizationType.USERS_OR_SERVICES;
+    roles?: never;
+    reason?: never;
+    appPolicy?: never;
+} | {
+    authType: AuthorizationType.ROLES;
+    roles: readonly [string, ...string[]];
+    reason?: never;
+    appPolicy?: never;
+} | {
+    authType: AuthorizationType.ANONYMOUS;
+    reason: string;
+    roles?: never;
+    appPolicy?: never;
+} | {
+    authType: AuthorizationType.CUSTOM;
+    appPolicy: TPolicy;
+    roles?: never;
+    reason?: never;
+};
+export declare const AUTHORIZATION_METADATA_KEY = "webpieces:authorization";
+export declare const AUTHORIZATION_METHODS_KEY = "webpieces:authorization-methods";
+/** Runtime checks also protect JavaScript and type-erased callers. */
+export declare class AuthorizationDeclaration {
+    static validate(value: AuthorizationRequirement<unknown>): void;
+}
+export declare function WpAuthorization<TPolicy = never>(policy: AuthorizationRequirement<TPolicy>): MethodDecorator;
+export declare function getAuthorization(apiClass: Function, methodName: string): AuthorizationRequirement<unknown> | undefined;