feat: snapshot every plugin API sub-path

docs/development/contracts.md

@@ -31,15 +31,19 @@ contract shows up as a diff instead of a surprise after the release:
 - `openapi.json` is the REST API document the published reference is built
   from. Regenerate it with `npm run generate:openapi`; `npm run check:openapi`
   fails when it is stale.
-- `etc/api/*.api.md` are the API Extractor reports of the five entry points
-  #595 covers first — `ldap-rest`, `./plugin`, `./hooks`, `./ldapactions` and
-  `./expressformatedresponses` — one file per sub-path. Regenerate them with
-  `npm run snapshot:api`; `npm run check:api`, part of `npm run check`, fails
-  when one is stale. A report lists what the entry exports and the shapes of
-  the types those exports reference, including the types the entry does not
-  export itself, so a change to `RouteDefinition` or `OptionSet` shows up even
-  though a plugin cannot name them. The 66 `./plugin-*` entries come with the
-  modularization, see [the plan](modularization-plan.md).
+- `etc/api/*.api.md` are the API Extractor reports, one file per sub-path:
+  the five main entry points — `ldap-rest`, `./plugin`, `./hooks`,
+  `./ldapactions` and `./expressformatedresponses` — and every `./plugin-*`
+  entry. A new plugin gets its report from `package.json`, without another
+  list to update. Regenerate them with `npm run snapshot:api`;
+  `npm run check:api`, part of `npm run check`, fails when one is stale. A
+  report lists what the entry exports and the shapes of the types those
+  exports reference, including the types the entry does not export itself, so
+  a change to `RouteDefinition` or `OptionSet` shows up even though a plugin
+  cannot name them. A declaration a plugin report shares verbatim with a
+  core report is dropped from the plugin report: the core report already
+  gates it, and repeating it would rewrite every plugin report on a core
+  change.
 
 The snapshot records what the parser reads. A narrowed `choices` list, a
 raised `min` or a lowered `max` is checked when a plugin reads its options,
@@ -69,9 +73,9 @@ the exported one, or a member of an exported namespace. Renaming a type only
 reachable through a signature is not a break: nobody can write its name, and
 the declarations that use it are reported as changed. A changed declaration is
 printed for review and does not fail the job yet: telling an added optional
-member from a narrowed union needs more than a line diff, and comes with the
-`./plugin-*` reports. Renaming an option is a deprecation, not a removal, as
-long as the old CLI name and environment variable stay in its `aliases` and
+member from a narrowed union needs more than a line diff. Renaming an
+option is a deprecation, not a removal, as long as the old CLI name and
+environment variable stay in its `aliases` and
 `envAliases`. Adding a union variant, a field or an optional parameter is
 additive, and so is a request union with an alternative that still accepts
 everything the base did — in a response the client reads every alternative,

etc/api/plugin-auth-auth.options.api.md

@@ -0,0 +1,194 @@
+## API Report File for "ldap-rest"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @public (undocumented)
+type ArrayKind = 'identifiers' | 'dns' | 'phrases';
+
+// @public (undocumented)
+interface ArrayOption extends OptionSpec<string[]> {
+    readonly kind?: ArrayKind;
+    readonly plural?: string;
+    // (undocumented)
+    readonly type: 'array';
+}
+
+// @public (undocumented)
+interface BooleanOption extends OptionSpec<boolean> {
+    // (undocumented)
+    readonly type: 'boolean';
+}
+
+// @public (undocumented)
+export type CrowdsecOptions = OptionsOf<typeof crowdsecOptions>;
+
+// @public (undocumented)
+export const crowdsecOptions: {
+    crowdsec_url: StringOption;
+    crowdsec_api_key: StringOption;
+    crowdsec_cache_ttl: NumberOption;
+};
+
+// @public (undocumented)
+export function crowdsecOptionsOf(config: Config): CrowdsecOptions;
+
+// @public (undocumented)
+export type DynamicOptions = OptionsOf<typeof dynamicOptions>;
+
+// @public (undocumented)
+export const dynamicOptions: {
+    authz_dynamic_bypass: ArrayOption;
+    authz_dynamic_base: StringOption;
+    authz_dynamic_cache_ttl: NumberOption;
+    authz_dynamic_token_attribute: StringOption;
+    authz_dynamic_config_attribute: StringOption;
+    authz_dynamic_tenant_attribute: StringOption;
+    authz_dynamic_reload_endpoint: BooleanOption;
+};
+
+// @public (undocumented)
+export function dynamicOptionsOf(config: Config): DynamicOptions;
+
+// @public (undocumented)
+export type FakeOptions = OptionsOf<typeof fakeOptions>;
+
+// @public (undocumented)
+export const fakeOptions: {
+    auth_fake_user: StringOption;
+};
+
+// @public (undocumented)
+export type HmacOptions = OptionsOf<typeof hmacOptions>;
+
+// @public (undocumented)
+export const hmacOptions: {
+    auth_hmac: ArrayOption;
+    auth_hmac_window: NumberOption;
+};
+
+// @public (undocumented)
+export function hmacOptionsOf(config: Config): HmacOptions;
+
+// @public (undocumented)
+interface JsonOption<T> extends OptionSpec<T> {
+    // (undocumented)
+    readonly type: 'json';
+}
+
+// @public (undocumented)
+export type Linid1Options = OptionsOf<typeof linid1Options>;
+
+// @public (undocumented)
+export const linid1Options: {
+    authz_local_admin_attribute: StringOption;
+    authz_global_branch: ArrayOption;
+    authz_global_write_branch: ArrayOption;
+    authz_global_organization: StringOption;
+};
+
+// @public (undocumented)
+export type LlngOptions = OptionsOf<typeof llngOptions>;
+
+// @public (undocumented)
+export const llngOptions: {
+    llng_ini: StringOption;
+    llng_username_header: StringOption;
+};
+
+// @public (undocumented)
+interface NumberOption extends OptionSpec<number> {
+    // (undocumented)
+    readonly max?: number;
+    // (undocumented)
+    readonly min?: number;
+    // (undocumented)
+    readonly type: 'number';
+}
+
+// @public (undocumented)
+export type OpenidconnectOptions = OptionsOf<typeof openidconnectOptions>;
+
+// @public (undocumented)
+export const openidconnectOptions: {
+    oidc_server: StringOption;
+    oidc_username_claim: StringOption;
+    oidc_client_id: StringOption;
+    oidc_client_secret: StringOption;
+    base_url: StringOption;
+};
+
+// @public (undocumented)
+export type PerBranchOptions = OptionsOf<typeof perBranchOptions>;
+
+// @public (undocumented)
+export const perBranchOptions: {
+    authz_per_branch_config: JsonOption<AuthConfig>;
+    authz_per_branch_cache_ttl: NumberOption;
+    ldap_group_member_attribute: StringOption;
+};
+
+// @public (undocumented)
+export function perBranchOptionsOf(config: Config): PerBranchOptions;
+
+// @public (undocumented)
+export type PerRouteOptions = OptionsOf<typeof perRouteOptions>;
+
+// @public (undocumented)
+export const perRouteOptions: {
+    authz_per_route: ArrayOption;
+};
+
+// @public (undocumented)
+export type RateLimitOptions = OptionsOf<typeof rateLimitOptions>;
+
+// @public (undocumented)
+export const rateLimitOptions: {
+    rate_limit_window_ms: NumberOption;
+    rate_limit_max: NumberOption;
+};
+
+// @public (undocumented)
+export function rateLimitOptionsOf(config: Config): RateLimitOptions;
+
+// @public (undocumented)
+interface StringOption extends OptionSpec<string> {
+    readonly choices?: readonly string[];
+    // (undocumented)
+    readonly type: 'string';
+}
+
+// @public (undocumented)
+export type TokenOptions = OptionsOf<typeof tokenOptions>;
+
+// @public (undocumented)
+export const tokenOptions: {
+    auth_token: ArrayOption;
+};
+
+// @public (undocumented)
+export type TotpOptions = OptionsOf<typeof totpOptions>;
+
+// @public (undocumented)
+export const totpOptions: {
+    auth_totp: ArrayOption;
+    auth_totp_window: NumberOption;
+    auth_totp_step: NumberOption;
+};
+
+// @public
+export function totpOptionsOf(config: Config): TotpOptions;
+
+// @public (undocumented)
+export type TrustedProxyOptions = OptionsOf<typeof trustedProxyOptions>;
+
+// @public (undocumented)
+export const trustedProxyOptions: {
+    trusted_proxy: ArrayOption;
+    trusted_proxy_auth_header: StringOption;
+};
+
+// (No @packageDocumentation comment for this package)
+
+```

etc/api/plugin-auth-authzdynamic.api.md

@@ -0,0 +1,125 @@
+## API Report File for "ldap-rest"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Entry } from 'ldapts';
+import express from 'express';
+import type { Express as Express_2 } from 'express';
+import pLimit from 'p-limit';
+import type { Request as Request_2 } from 'express';
+import type { Response as Response_2 } from 'express';
+import type { SearchOptions } from 'ldapts';
+import type { SearchResult } from 'ldapts';
+import { Server } from 'http';
+import type winston from 'winston';
+
+// @public (undocumented)
+type ArrayKind = 'identifiers' | 'dns' | 'phrases';
+
+// @public (undocumented)
+interface ArrayOption extends OptionSpec<string[]> {
+    readonly kind?: ArrayKind;
+    readonly plural?: string;
+    // (undocumented)
+    readonly type: 'array';
+}
+
+// @public (undocumented)
+class AuthzDynamic extends AuthBase {
+    constructor(server: DM);
+    afterChain(req: DmRequest, res: Response_2, next: () => void): void;
+    // (undocumented)
+    afterLoad(): void;
+    // (undocumented)
+    api(app: Express_2): void;
+    // (undocumented)
+    authMethod(req: DmRequest, res: Response_2, next: () => void): void;
+    getConfigApiData(): Record<string, unknown>;
+    hooks: Hooks;
+    protected identitySource(): string;
+    // (undocumented)
+    name: string;
+    // (undocumented)
+    static optionDefinitions: {
+        authz_dynamic_bypass: ArrayOption;
+        authz_dynamic_base: StringOption;
+        authz_dynamic_cache_ttl: NumberOption;
+        authz_dynamic_token_attribute: StringOption;
+        authz_dynamic_config_attribute: StringOption;
+        authz_dynamic_tenant_attribute: StringOption;
+        authz_dynamic_reload_endpoint: BooleanOption;
+    };
+    reload(): Promise<void>;
+    // (undocumented)
+    roles: Role[];
+    // (undocumented)
+    _tokens(): TokenEntry[];
+}
+export default AuthzDynamic;
+
+// @public
+export interface AuthzDynamicRequest extends DmRequest {
+    // (undocumented)
+    authzToken?: TokenEntry;
+}
+
+// @public (undocumented)
+interface BooleanOption extends OptionSpec<boolean> {
+    // (undocumented)
+    readonly type: 'boolean';
+}
+
+// @public (undocumented)
+export interface BranchAcl {
+    // (undocumented)
+    delete?: boolean;
+    // (undocumented)
+    dn: string;
+    // (undocumented)
+    read?: boolean;
+    // (undocumented)
+    write?: boolean;
+}
+
+// @public (undocumented)
+interface NumberOption extends OptionSpec<number> {
+    // (undocumented)
+    readonly max?: number;
+    // (undocumented)
+    readonly min?: number;
+    // (undocumented)
+    readonly type: 'number';
+}
+
+// @public (undocumented)
+interface StringOption extends OptionSpec<string> {
+    readonly choices?: readonly string[];
+    // (undocumented)
+    readonly type: 'string';
+}
+
+// @public (undocumented)
+export interface TokenConfig {
+    // (undocumented)
+    bases?: BranchAcl[];
+    // (undocumented)
+    tenant?: string;
+}
+
+// @public (undocumented)
+export interface TokenEntry {
+    // (undocumented)
+    bases: BranchAcl[];
+    // (undocumented)
+    cn: string;
+    // (undocumented)
+    dn: string;
+    // (undocumented)
+    hash: string;
+    // (undocumented)
+    tenant: string;
+}
+
+```

etc/api/plugin-auth-authzdynamichash.api.md

@@ -0,0 +1,21 @@
+## API Report File for "ldap-rest"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @public
+export function ssha(password: string, salt?: Buffer): string;
+
+// @public
+export type SshaAlgo = 'sha1' | 'sha256' | 'sha512';
+
+// @public (undocumented)
+export function sshaHash(algo: SshaAlgo, password: string, salt?: Buffer): string;
+
+// @public
+export function verifyLdapPassword(provided: string, stored: string): boolean;
+
+// (No @packageDocumentation comment for this package)
+
+```