@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.
Files changed (54) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +51 -15
  3. package/THIRD_PARTY_NOTICES.md +31 -0
  4. package/dist/express.cjs +157 -0
  5. package/dist/express.cjs.map +1 -0
  6. package/dist/express.d.cts +90 -0
  7. package/dist/express.d.ts +90 -0
  8. package/dist/express.js +127 -0
  9. package/dist/express.js.map +1 -0
  10. package/dist/index.cjs +1254 -0
  11. package/dist/index.cjs.map +1 -0
  12. package/dist/index.d.cts +67 -0
  13. package/dist/index.d.ts +67 -0
  14. package/dist/index.js +499 -0
  15. package/dist/index.js.map +1 -0
  16. package/dist/nestjs.cjs +1395 -0
  17. package/dist/nestjs.cjs.map +1 -0
  18. package/dist/nestjs.d.cts +153 -0
  19. package/dist/nestjs.d.ts +153 -0
  20. package/dist/nestjs.js +637 -0
  21. package/dist/nestjs.js.map +1 -0
  22. package/dist/types-CGtRnj59.d.cts +193 -0
  23. package/dist/types-CGtRnj59.d.ts +193 -0
  24. package/dist/webhook.cjs +8 -6
  25. package/dist/webhook.cjs.map +1 -1
  26. package/dist/webhook.d.cts +9 -3
  27. package/dist/webhook.d.ts +9 -3
  28. package/dist/webhook.js +8 -6
  29. package/dist/webhook.js.map +1 -1
  30. package/docs/bff-express.md +1314 -0
  31. package/docs/consumers.md +10 -2
  32. package/docs/error.md +195 -10
  33. package/docs/examples/auth-verify-readme.ts +24 -0
  34. package/docs/examples/bff-express.ts +370 -0
  35. package/docs/examples/bff-proxy.ts +335 -0
  36. package/docs/examples/bff-redis-lock.ts +187 -0
  37. package/docs/examples/bff-revocation.ts +136 -0
  38. package/docs/examples/env.ts +52 -1
  39. package/docs/examples/token-commonjs.cjs +95 -0
  40. package/docs/examples/token-express.ts +56 -0
  41. package/docs/examples/token-fetch.ts +24 -0
  42. package/docs/examples/token-nestjs-jest.ts +77 -0
  43. package/docs/examples/token-nestjs.ts +127 -0
  44. package/docs/examples/token-socket.ts +59 -0
  45. package/docs/examples/token-testing.ts +100 -0
  46. package/docs/examples/token-verifier.ts +132 -0
  47. package/docs/examples/user-events.ts +110 -0
  48. package/docs/examples/webhook-verifier.ts +54 -0
  49. package/docs/login-web.md +39 -7
  50. package/docs/memulai.md +94 -14
  51. package/docs/server-ke-server.md +12 -0
  52. package/docs/verifikasi-token.md +1219 -0
  53. package/docs/webhook.md +191 -6
  54. package/package.json +61 -5
@@ -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 };