@plasgos/auth-verify 0.1.0-next.2 → 0.1.0-next.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +51 -15
- package/THIRD_PARTY_NOTICES.md +31 -0
- package/dist/express.cjs +157 -0
- package/dist/express.cjs.map +1 -0
- package/dist/express.d.cts +90 -0
- package/dist/express.d.ts +90 -0
- package/dist/express.js +127 -0
- package/dist/express.js.map +1 -0
- package/dist/index.cjs +1254 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +67 -0
- package/dist/index.d.ts +67 -0
- package/dist/index.js +499 -0
- package/dist/index.js.map +1 -0
- package/dist/nestjs.cjs +1395 -0
- package/dist/nestjs.cjs.map +1 -0
- package/dist/nestjs.d.cts +153 -0
- package/dist/nestjs.d.ts +153 -0
- package/dist/nestjs.js +637 -0
- package/dist/nestjs.js.map +1 -0
- package/dist/types-CGtRnj59.d.cts +193 -0
- package/dist/types-CGtRnj59.d.ts +193 -0
- package/dist/webhook.cjs +8 -6
- package/dist/webhook.cjs.map +1 -1
- package/dist/webhook.d.cts +9 -3
- package/dist/webhook.d.ts +9 -3
- package/dist/webhook.js +8 -6
- package/dist/webhook.js.map +1 -1
- package/docs/bff-express.md +1314 -0
- package/docs/consumers.md +10 -2
- package/docs/error.md +195 -10
- package/docs/examples/auth-verify-readme.ts +24 -0
- package/docs/examples/bff-express.ts +370 -0
- package/docs/examples/bff-proxy.ts +335 -0
- package/docs/examples/bff-redis-lock.ts +187 -0
- package/docs/examples/bff-revocation.ts +136 -0
- package/docs/examples/env.ts +52 -1
- package/docs/examples/token-commonjs.cjs +95 -0
- package/docs/examples/token-express.ts +56 -0
- package/docs/examples/token-fetch.ts +24 -0
- package/docs/examples/token-nestjs-jest.ts +77 -0
- package/docs/examples/token-nestjs.ts +127 -0
- package/docs/examples/token-socket.ts +59 -0
- package/docs/examples/token-testing.ts +100 -0
- package/docs/examples/token-verifier.ts +132 -0
- package/docs/examples/user-events.ts +110 -0
- package/docs/examples/webhook-verifier.ts +54 -0
- package/docs/login-web.md +39 -7
- package/docs/memulai.md +94 -14
- package/docs/server-ke-server.md +12 -0
- package/docs/verifikasi-token.md +1219 -0
- package/docs/webhook.md +191 -6
- package/package.json +61 -5
package/dist/nestjs.d.ts
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import { DynamicModule, ModuleMetadata, FactoryProvider, CanActivate, ExecutionContext, CustomDecorator } from '@nestjs/common';
|
|
2
|
+
import { A as AccessPrincipal, U as UserAccessPrincipal, b as AccessTokenVerifierOptions, a as AccessTokenVerifier } from './types-CGtRnj59.js';
|
|
3
|
+
export { S as ServiceAccessPrincipal, V as VerifiedAccessTokenClaims } from './types-CGtRnj59.js';
|
|
4
|
+
import { Reflector } from '@nestjs/core';
|
|
5
|
+
export { AuthVerifyError, AuthVerifyReason, ConfigError } from '@plasgos/auth-shared';
|
|
6
|
+
|
|
7
|
+
/** Options for one API: user tokens only, or both kinds with `allowServiceTokens: true`. */
|
|
8
|
+
type ModuleOptions = AccessTokenVerifierOptions | AccessTokenVerifierOptions<AccessPrincipal>;
|
|
9
|
+
/**
|
|
10
|
+
* The options of `PlasgosAuthModule.forRootAsync`: a factory that returns the verifier options, its
|
|
11
|
+
* injected providers and the modules that export them.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* PlasgosAuthModule.forRootAsync({
|
|
15
|
+
* imports: [ConfigModule],
|
|
16
|
+
* inject: [ConfigService],
|
|
17
|
+
* useFactory: (config: ConfigService) => ({ environment: "production", issuer: config.get("ISSUER"), audience: config.get("AUDIENCE") }),
|
|
18
|
+
* });
|
|
19
|
+
*/
|
|
20
|
+
interface PlasgosAuthModuleAsyncOptions {
|
|
21
|
+
/** Modules that export the providers `inject` names. */
|
|
22
|
+
imports?: ModuleMetadata["imports"] | undefined;
|
|
23
|
+
/** Providers passed to `useFactory`, in order. */
|
|
24
|
+
inject?: FactoryProvider["inject"] | undefined;
|
|
25
|
+
/** Returns the options of `createAccessTokenVerifier`, or a promise of them. */
|
|
26
|
+
useFactory: (...args: never[]) => ModuleOptions | Promise<ModuleOptions>;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* A global NestJS module that provides the access-token verifier under `PLASGOS_ACCESS_TOKEN_VERIFIER`
|
|
30
|
+
* and `PlasgosAccessTokenGuard` to the whole app. Import it once, in the root module. The verifier is
|
|
31
|
+
* created with `createAccessTokenVerifier` when Nest builds the module, so a wrong option stops the
|
|
32
|
+
* app at start with one `ConfigError` listing every problem.
|
|
33
|
+
*
|
|
34
|
+
* @example
|
|
35
|
+
* @Module({
|
|
36
|
+
* imports: [
|
|
37
|
+
* PlasgosAuthModule.forRoot({
|
|
38
|
+
* environment: "production",
|
|
39
|
+
* issuer: "https://accounts.plasgos.co.id",
|
|
40
|
+
* audience: "https://api.plasgos.co.id/crm",
|
|
41
|
+
* requireClaims: ["plasgos_public_id", "cv"],
|
|
42
|
+
* isRevoked: (principal) => revocations.isRevoked(principal),
|
|
43
|
+
* }),
|
|
44
|
+
* ],
|
|
45
|
+
* })
|
|
46
|
+
* export class AppModule {}
|
|
47
|
+
*/
|
|
48
|
+
declare class PlasgosAuthModule {
|
|
49
|
+
/**
|
|
50
|
+
* The module with fixed options (the options of `createAccessTokenVerifier`). By default the options
|
|
51
|
+
* are user-only and `isRevoked` receives a `UserAccessPrincipal`; to accept service tokens too, name
|
|
52
|
+
* the principal type: `forRoot<AccessPrincipal>({ …, allowServiceTokens: true })`.
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* PlasgosAuthModule.forRoot({ environment: "sandbox", issuer, audience, isRevoked: () => false });
|
|
56
|
+
*/
|
|
57
|
+
static forRoot<P extends AccessPrincipal = UserAccessPrincipal>(options: AccessTokenVerifierOptions<P>): DynamicModule;
|
|
58
|
+
/**
|
|
59
|
+
* The module with options from a factory, for example from a config service. A `ConfigError` from
|
|
60
|
+
* the returned options, or an error of the factory, fails the app's start.
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* PlasgosAuthModule.forRootAsync({ inject: [ConfigService], useFactory: (config: ConfigService) => config.get("plasgos") });
|
|
64
|
+
*/
|
|
65
|
+
static forRootAsync(options: PlasgosAuthModuleAsyncOptions): DynamicModule;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* A NestJS guard that lets a request through only with a valid Plasgos access token. It uses the
|
|
70
|
+
* verifier that `PlasgosAuthModule.forRoot` or `forRootAsync` provides, and the route requirements of
|
|
71
|
+
* `@RequireScopes` (class and method scopes add up) and `@RequireRecentAuth` (the method overrides the
|
|
72
|
+
* class). It reads `Authorization` and `X-Request-Id` (for the verifier's `onReject` event).
|
|
73
|
+
*
|
|
74
|
+
* - Token accepted: stores the principal on the request (read it with `@PlasgosPrincipal()`) and lets
|
|
75
|
+
* the request through.
|
|
76
|
+
* - Token refused (`AuthVerifyError`): sets `Cache-Control: no-store`, and `WWW-Authenticate` when the
|
|
77
|
+
* error has a challenge, on the response (Express and Fastify), and throws
|
|
78
|
+
* `HttpException({ error: errorCode }, status)`, so Nest answers 401, 403 or 503 with that JSON body.
|
|
79
|
+
* An app-wide exception filter that rewrites `HttpException` answers also rewrites this body.
|
|
80
|
+
* - Any other error (for example one thrown by your `isRevoked`) propagates unchanged to Nest's
|
|
81
|
+
* exception layer.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* @Controller("contacts")
|
|
85
|
+
* @UseGuards(PlasgosAccessTokenGuard)
|
|
86
|
+
* @RequireScopes("crm:access")
|
|
87
|
+
* export class ContactsController {
|
|
88
|
+
* @Get()
|
|
89
|
+
* list(@PlasgosPrincipal() principal: UserAccessPrincipal) {
|
|
90
|
+
* return this.contacts.list(principal.claims.plasgos_public_id);
|
|
91
|
+
* }
|
|
92
|
+
* }
|
|
93
|
+
*/
|
|
94
|
+
declare class PlasgosAccessTokenGuard implements CanActivate {
|
|
95
|
+
private readonly verifier;
|
|
96
|
+
private readonly reflector;
|
|
97
|
+
constructor(verifier: AccessTokenVerifier<AccessPrincipal>, reflector: Reflector);
|
|
98
|
+
/**
|
|
99
|
+
* Verifies the request's token against the route requirements. Resolves `true`, or rejects with an
|
|
100
|
+
* `HttpException` for a refused token, or with the verifier's own non-token error.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* const allowed = await guard.canActivate(context);
|
|
104
|
+
*/
|
|
105
|
+
canActivate(context: ExecutionContext): Promise<boolean>;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Requires scopes on a controller or a route; `PlasgosAccessTokenGuard` refuses a token that lacks any
|
|
110
|
+
* of them with 403 `insufficient_scope`. Scopes on the class and on the method add up. Throws
|
|
111
|
+
* `TypeError` at decoration time without a scope, or for a value that is not an OAuth scope token.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* @Controller("contacts")
|
|
115
|
+
* @UseGuards(PlasgosAccessTokenGuard)
|
|
116
|
+
* @RequireScopes("crm:access")
|
|
117
|
+
* export class ContactsController {}
|
|
118
|
+
*/
|
|
119
|
+
declare function RequireScopes(...scopes: string[]): CustomDecorator;
|
|
120
|
+
/**
|
|
121
|
+
* Requires a recent login on a controller or a route: `PlasgosAccessTokenGuard` refuses a token whose
|
|
122
|
+
* `auth_time` is older than `maxAgeSeconds` (default 600) with 401 `insufficient_user_authentication`
|
|
123
|
+
* and `max_age=<seconds>` in `WWW-Authenticate`. The value on the method overrides the one on the
|
|
124
|
+
* class. Throws `TypeError` at decoration time when `maxAgeSeconds` is not a positive integer.
|
|
125
|
+
*
|
|
126
|
+
* @example
|
|
127
|
+
* @Post("export")
|
|
128
|
+
* @RequireRecentAuth(300)
|
|
129
|
+
* exportContacts() {}
|
|
130
|
+
*/
|
|
131
|
+
declare function RequireRecentAuth(maxAgeSeconds?: number): CustomDecorator;
|
|
132
|
+
/**
|
|
133
|
+
* Injects the principal that `PlasgosAccessTokenGuard` verified into a route parameter. On a route
|
|
134
|
+
* without the guard it throws `Error` (a wiring mistake, answered with 500).
|
|
135
|
+
*
|
|
136
|
+
* @example
|
|
137
|
+
* @Get("me")
|
|
138
|
+
* me(@PlasgosPrincipal() principal: UserAccessPrincipal) {
|
|
139
|
+
* return { publicId: principal.claims.plasgos_public_id };
|
|
140
|
+
* }
|
|
141
|
+
*/
|
|
142
|
+
declare const PlasgosPrincipal: () => ParameterDecorator;
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* The injection token of the `AccessTokenVerifier` that `PlasgosAuthModule` provides.
|
|
146
|
+
*
|
|
147
|
+
* @example
|
|
148
|
+
* constructor(@Inject(PLASGOS_ACCESS_TOKEN_VERIFIER) private readonly verifier: AccessTokenVerifier) {}
|
|
149
|
+
*/
|
|
150
|
+
declare const PLASGOS_ACCESS_TOKEN_VERIFIER = "PLASGOS_ACCESS_TOKEN_VERIFIER";
|
|
151
|
+
|
|
152
|
+
export { AccessPrincipal, AccessTokenVerifier, AccessTokenVerifierOptions, PLASGOS_ACCESS_TOKEN_VERIFIER, PlasgosAccessTokenGuard, PlasgosAuthModule, PlasgosPrincipal, RequireRecentAuth, RequireScopes, UserAccessPrincipal };
|
|
153
|
+
export type { PlasgosAuthModuleAsyncOptions };
|