@c9up/visa 0.1.0

package/dist/VisaProvider.js

@@ -0,0 +1,153 @@
+/**
+ * Wires `config/visa.ts` into the container, and mounts the endpoints that
+ * need no human.
+ *
+ * `/token`, `/revoke` and `/introspect` are machine-to-machine: the spec says
+ * exactly what goes in and what comes out, so the provider owns them.
+ *
+ * `/authorize` is NOT mounted, and that is deliberate rather than unfinished.
+ * It needs two things visa has no opinion about: who is signed in — warden's
+ * business — and what a consent screen looks like, which is the application's.
+ * A route that guessed either would be wrong in a way that is hard to notice:
+ * a server that shows no consent screen grants silently, and one that assumes
+ * a session shape signs the wrong user in. `visa.authorize()` gives you the
+ * decision; the page around it is yours. The README shows the ten lines.
+ *
+ * Duck-typed throughout: visa must not import its host's HTTP types.
+ */
+import "./augmentations.js";
+import { OAuthError } from "./errors.js";
+import { clearVisa, getVisa, setVisa } from "./services/main.js";
+import { VisaManager } from "./VisaManager.js";
+export default class VisaProvider {
+    app;
+    #owned;
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        this.app.container.singleton(VisaManager, () => {
+            const config = this.app.config.get("visa");
+            if (config === undefined) {
+                throw new Error("[visa] no `config/visa.ts` — run `ream configure @c9up/visa`.");
+            }
+            const manager = new VisaManager(config);
+            setVisa(manager);
+            return manager;
+        });
+        this.app.container.singleton("visa", () => this.app.container.resolve(VisaManager));
+    }
+    async boot() {
+        const manager = await this.app.container.resolve(VisaManager);
+        this.#owned = manager;
+        setVisa(manager);
+    }
+    async start() {
+        if (!this.app.container.has("router"))
+            return;
+        const router = await this.app.container.resolve("router");
+        const manager = await this.app.container.resolve(VisaManager);
+        const config = this.app.config.get("visa");
+        const prefix = config?.prefix ?? "/oauth";
+        router.post(`${prefix}/token`, async (ctx) => {
+            await this.#answer(ctx, async () => {
+                const body = ctx.request.all();
+                const credentials = manager.readCredentials({
+                    body,
+                    ...readAuthorization(ctx),
+                });
+                const tokens = await manager.token(body, credentials);
+                // No store may keep a token response: it carries credentials
+                // (RFC 6749 §5.1), and a shared cache would hand them to the
+                // next caller.
+                ctx.response.header("cache-control", "no-store");
+                ctx.response.header("pragma", "no-cache");
+                return tokens;
+            });
+        });
+        router.post(`${prefix}/introspect`, async (ctx) => {
+            await this.#answer(ctx, async () => {
+                const body = ctx.request.all();
+                const credentials = manager.readCredentials({
+                    body,
+                    ...readAuthorization(ctx),
+                });
+                ctx.response.header("cache-control", "no-store");
+                return manager.introspect(body, credentials);
+            });
+        });
+        router.post(`${prefix}/revoke`, async (ctx) => {
+            await this.#answer(ctx, async () => {
+                const body = ctx.request.all();
+                const credentials = manager.readCredentials({
+                    body,
+                    ...readAuthorization(ctx),
+                });
+                await manager.revoke(body, credentials);
+                // RFC 7009 §2.2: 200 with an empty body, whatever the token was.
+                ctx.response.status(200);
+                return null;
+            });
+        });
+        // RFC 8414 — what a client fetches to discover the endpoints.
+        router.get("/.well-known/oauth-authorization-server", async (ctx) => {
+            ctx.response.header("content-type", "application/json");
+            ctx.response.send({
+                issuer: manager.issuer,
+                authorization_endpoint: `${manager.issuer}${prefix}/authorize`,
+                token_endpoint: `${manager.issuer}${prefix}/token`,
+                introspection_endpoint: `${manager.issuer}${prefix}/introspect`,
+                revocation_endpoint: `${manager.issuer}${prefix}/revoke`,
+                response_types_supported: ["code"],
+                grant_types_supported: [
+                    "authorization_code",
+                    "refresh_token",
+                    "client_credentials",
+                ],
+                // S256 only unless the application turned `plain` back on.
+                code_challenge_methods_supported: config?.allowPlainChallenge === true ? ["S256", "plain"] : ["S256"],
+                token_endpoint_auth_methods_supported: [
+                    "client_secret_basic",
+                    "client_secret_post",
+                    "none",
+                ],
+            });
+        });
+    }
+    async shutdown() {
+        if (this.#owned !== undefined && getVisa() === this.#owned)
+            clearVisa();
+        this.#owned = undefined;
+    }
+    /**
+     * Run a handler and turn an `OAuthError` into the body the spec names.
+     *
+     * Anything else is rethrown: an unexpected failure is the application's
+     * exception handler's business, and dressing it as an OAuth error would
+     * tell a client its request was bad when the server broke.
+     */
+    async #answer(ctx, work) {
+        try {
+            const body = await work();
+            if (body !== null)
+                ctx.response.send(body);
+            else
+                ctx.response.send("");
+        }
+        catch (error) {
+            if (!(error instanceof OAuthError))
+                throw error;
+            ctx.response.status(error.status);
+            if (error.code === "invalid_client") {
+                // §5.2: a 401 has to say how to authenticate.
+                ctx.response.header("www-authenticate", 'Basic realm="oauth"');
+            }
+            ctx.response.send(error.toResponse());
+        }
+    }
+}
+function readAuthorization(ctx) {
+    const header = ctx.request.header("authorization");
+    return header === undefined ? {} : { authorization: header };
+}
+//# sourceMappingURL=VisaProvider.js.map

package/dist/VisaProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VisaProvider.js","sourceRoot":"","sources":["../src/VisaProvider.ts"],"names":[],"mappings":"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"}

package/dist/augmentations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make(...)` returns for the
+ * token visa binds.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the ones it owns. Without this,
+ * resolving by the string token answers `unknown` and every call site has to
+ * assert a type it cannot prove — on the object that mints credentials, which
+ * is the last place to be guessing.
+ *
+ * Loaded from the barrel and from the provider, so importing visa anywhere is
+ * enough; nobody writes a `declare module` of their own.
+ *
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
+ * import, and a `declare module` for a specifier that does not resolve is
+ * simply inert.
+ */
+import type { VisaManager } from "./VisaManager.js";
+declare module "@c9up/ream/types" {
+    interface ContainerBindings {
+        /** The authorization server, bound by `VisaProvider`. */
+        visa: VisaManager;
+    }
+}
+//# sourceMappingURL=augmentations.d.ts.map

package/dist/augmentations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augmentations.d.ts","sourceRoot":"","sources":["../src/augmentations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,QAAQ,kBAAkB,CAAC;IACjC,UAAU,iBAAiB;QAC1B,yDAAyD;QACzD,IAAI,EAAE,WAAW,CAAC;KAClB;CACD"}

package/dist/augmentations.js

@@ -0,0 +1,19 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make(...)` returns for the
+ * token visa binds.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the ones it owns. Without this,
+ * resolving by the string token answers `unknown` and every call site has to
+ * assert a type it cannot prove — on the object that mints credentials, which
+ * is the last place to be guessing.
+ *
+ * Loaded from the barrel and from the provider, so importing visa anywhere is
+ * enough; nobody writes a `declare module` of their own.
+ *
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
+ * import, and a `declare module` for a specifier that does not resolve is
+ * simply inert.
+ */
+export {};
+//# sourceMappingURL=augmentations.js.map

package/dist/augmentations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"augmentations.js","sourceRoot":"","sources":["../src/augmentations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/authorize.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The authorization endpoint.
+ *
+ * It is the half a human sees, and the half where an error must NOT be
+ * redirected: if the redirect URI is missing, unregistered or malformed, the
+ * server tells the user and stops (§4.1.2.1). Bouncing the error to an
+ * unverified URI is how an attacker learns that a client exists and gets a
+ * page of their choosing loaded in the user's session.
+ */
+import { OAuthError } from "./errors.js";
+import type { VisaStore } from "./store.js";
+import type { Client } from "./types.js";
+/** The query as it arrived, untrusted. */
+export interface AuthorizationRequest {
+    response_type?: string;
+    client_id?: string;
+    redirect_uri?: string;
+    scope?: string;
+    state?: string;
+    code_challenge?: string;
+    code_challenge_method?: string;
+    nonce?: string;
+    /** A client may ask to always see the consent screen. */
+    prompt?: string;
+}
+/** A request that passed every check, with the values it resolved to. */
+export interface ValidatedRequest {
+    client: Client;
+    redirectUri: string;
+    scopes: string[];
+    state: string | undefined;
+    codeChallenge: string;
+    codeChallengeMethod: "S256" | "plain";
+    nonce: string | undefined;
+}
+/**
+ * A failure that cannot be redirected — the user must be told directly.
+ *
+ * Separate from `OAuthError` because the CALLER has to treat it differently:
+ * render a page, never `Location:`.
+ */
+export declare class UnredirectableError extends Error {
+    readonly error: OAuthError;
+    constructor(error: OAuthError);
+}
+export interface AuthorizeOptions {
+    /** Lifetime of the code. Short on purpose — see `issueAuthorizationCode`. */
+    codeTtlSeconds?: number;
+    /**
+     * Accept `plain` as a code challenge method.
+     *
+     * NAMED DEVIATION — the spec allows `plain`; this refuses it by default.
+     * `plain` puts the verifier in the authorization request, so anything that
+     * can read that request (a log, a referrer, a proxy) can complete the
+     * exchange, which is precisely what PKCE exists to stop. Every client that
+     * can hash can use S256.
+     */
+    allowPlainChallenge?: boolean;
+}
+/**
+ * Check an authorization request. Throws `UnredirectableError` when the error
+ * must not be bounced back, `OAuthError` when it may.
+ */
+export declare function validateAuthorizationRequest(request: AuthorizationRequest, store: VisaStore, options?: AuthorizeOptions): Promise<ValidatedRequest>;
+/**
+ * Mint the code, once the user is known and has consented.
+ *
+ * Thirty seconds by default. A code is exchanged by a server the client
+ * controls, milliseconds after the redirect — a long window buys the client
+ * nothing and gives anything that can read a URL (a log, a referrer header, a
+ * shoulder) time to use it.
+ */
+export declare function issueAuthorizationCode(validated: ValidatedRequest, userId: string, store: VisaStore, options?: AuthorizeOptions, now?: Date): Promise<string>;
+/** Build the redirect a successful authorization ends on. */
+export declare function successRedirect(validated: ValidatedRequest, code: string): string;
+/** Build the redirect a refused or failed authorization ends on. */
+export declare function errorRedirect(redirectUri: string, error: OAuthError, state?: string): string;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/authorize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAqB,MAAM,EAAE,MAAM,YAAY,CAAC;AAE5D,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBACf,KAAK,EAAE,UAAU;CAK7B;AAED,MAAM,WAAW,gBAAgB;IAChC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CACjD,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,gBAAqB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAgD3B;AA2DD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,SAAS,EAAE,gBAAgB,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,gBAAqB,EAC9B,GAAG,GAAE,IAAiB,GACpB,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAC9B,SAAS,EAAE,gBAAgB,EAC3B,IAAI,EAAE,MAAM,GACV,MAAM,CAQR;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,UAAU,EACjB,KAAK,CAAC,EAAE,MAAM,GACZ,MAAM,CAQR"}

package/dist/authorize.js

@@ -0,0 +1,149 @@
+/**
+ * The authorization endpoint.
+ *
+ * It is the half a human sees, and the half where an error must NOT be
+ * redirected: if the redirect URI is missing, unregistered or malformed, the
+ * server tells the user and stops (§4.1.2.1). Bouncing the error to an
+ * unverified URI is how an attacker learns that a client exists and gets a
+ * page of their choosing loaded in the user's session.
+ */
+import { assertGrantAllowed, redirectUriMatches, resolveScopes, } from "./clients.js";
+import { hashSecret, randomToken } from "./crypto.js";
+import { OAuthError } from "./errors.js";
+/**
+ * A failure that cannot be redirected — the user must be told directly.
+ *
+ * Separate from `OAuthError` because the CALLER has to treat it differently:
+ * render a page, never `Location:`.
+ */
+export class UnredirectableError extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.name = "UnredirectableError";
+        this.error = error;
+    }
+}
+/**
+ * Check an authorization request. Throws `UnredirectableError` when the error
+ * must not be bounced back, `OAuthError` when it may.
+ */
+export async function validateAuthorizationRequest(request, store, options = {}) {
+    // Order matters: everything that decides WHERE an error may go has to be
+    // settled before any error is produced.
+    if (request.client_id === undefined || request.client_id === "") {
+        throw new UnredirectableError(new OAuthError("invalid_request", "client_id is required."));
+    }
+    const client = await store.findClient(request.client_id);
+    if (client === null) {
+        throw new UnredirectableError(new OAuthError("invalid_request", "Unknown client."));
+    }
+    const redirectUri = resolveRedirectUri(request.redirect_uri, client);
+    // From here the redirect URI is verified, so an error may travel back.
+    if (request.response_type !== "code") {
+        throw new OAuthError(request.response_type === undefined
+            ? "invalid_request"
+            : "unsupported_response_type", 
+        // The implicit grant is gone in 2.1, and `token` is its response
+        // type — saying so beats a blank refusal for whoever is porting.
+        request.response_type === "token"
+            ? "The implicit grant is not supported; use response_type=code."
+            : "Only response_type=code is supported.");
+    }
+    assertGrantAllowed(client, "authorization_code");
+    const { codeChallenge, codeChallengeMethod } = readChallenge(request, options);
+    const scopes = resolveScopes(request.scope, client);
+    return {
+        client,
+        redirectUri,
+        scopes,
+        state: request.state,
+        codeChallenge,
+        codeChallengeMethod,
+        nonce: request.nonce,
+    };
+}
+/**
+ * Which redirect URI this request lands on.
+ *
+ * Omitting it is allowed only when the client registered exactly one — with
+ * two or more, "the first one" would be a choice the server makes on the
+ * client's behalf, and the wrong choice sends the code elsewhere.
+ */
+function resolveRedirectUri(requested, client) {
+    if (client.redirectUris.length === 0) {
+        throw new UnredirectableError(new OAuthError("invalid_request", "This client has no redirect URI."));
+    }
+    if (requested === undefined || requested === "") {
+        const only = client.redirectUris[0];
+        if (client.redirectUris.length > 1 || only === undefined) {
+            throw new UnredirectableError(new OAuthError("invalid_request", "redirect_uri is required when a client registers more than one."));
+        }
+        return only;
+    }
+    if (!redirectUriMatches(requested, client.redirectUris)) {
+        throw new UnredirectableError(new OAuthError("invalid_request", "redirect_uri is not registered."));
+    }
+    return requested;
+}
+function readChallenge(request, options) {
+    const challenge = request.code_challenge;
+    if (challenge === undefined || challenge === "") {
+        // Mandatory in 2.1 for every client, confidential ones included.
+        throw new OAuthError("invalid_request", "code_challenge is required.");
+    }
+    const method = request.code_challenge_method ?? "plain";
+    if (method === "S256")
+        return { codeChallenge: challenge, codeChallengeMethod: "S256" };
+    if (method === "plain" && options.allowPlainChallenge === true) {
+        return { codeChallenge: challenge, codeChallengeMethod: "plain" };
+    }
+    throw new OAuthError("invalid_request", "code_challenge_method must be S256.");
+}
+/**
+ * Mint the code, once the user is known and has consented.
+ *
+ * Thirty seconds by default. A code is exchanged by a server the client
+ * controls, milliseconds after the redirect — a long window buys the client
+ * nothing and gives anything that can read a URL (a log, a referrer header, a
+ * shoulder) time to use it.
+ */
+export async function issueAuthorizationCode(validated, userId, store, options = {}, now = new Date()) {
+    const code = randomToken();
+    const ttl = options.codeTtlSeconds ?? 30;
+    const record = {
+        codeHash: hashSecret(code),
+        clientId: validated.client.id,
+        userId,
+        redirectUri: validated.redirectUri,
+        scopes: validated.scopes,
+        codeChallenge: validated.codeChallenge,
+        codeChallengeMethod: validated.codeChallengeMethod,
+        expiresAt: new Date(now.getTime() + ttl * 1000),
+        ...(validated.nonce === undefined ? {} : { nonce: validated.nonce }),
+    };
+    await store.saveAuthorizationCode(record);
+    return code;
+}
+/** Build the redirect a successful authorization ends on. */
+export function successRedirect(validated, code) {
+    const url = new URL(validated.redirectUri);
+    url.searchParams.set("code", code);
+    // Returned verbatim when the client sent one, absent when it did not —
+    // inventing a state would break the client's own CSRF check.
+    if (validated.state !== undefined)
+        url.searchParams.set("state", validated.state);
+    return url.toString();
+}
+/** Build the redirect a refused or failed authorization ends on. */
+export function errorRedirect(redirectUri, error, state) {
+    const url = new URL(redirectUri);
+    url.searchParams.set("error", error.code);
+    if (error.description !== undefined) {
+        url.searchParams.set("error_description", error.description);
+    }
+    if (state !== undefined)
+        url.searchParams.set("state", state);
+    return url.toString();
+}
+//# sourceMappingURL=authorize.js.map

package/dist/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"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"}

package/dist/clients.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Who is asking, and are they allowed to ask that.
+ *
+ * Three checks live here and each one closes a known attack: the redirect URI
+ * comparison (an open redirect on the client's domain turns into a stolen
+ * code), the client authentication (a leaked client_id is not a credential),
+ * and the scope narrowing (a client must not be able to grant itself more
+ * than it was registered for).
+ */
+import type { Client, ClientAuthMethod, GrantType } from "./types.js";
+/**
+ * Does this redirect URI match one the client registered?
+ *
+ * EXACT string comparison, as OAuth 2.1 §2.3.1 requires — with the single
+ * exception it names: a loopback redirect may differ in its port, because a
+ * native app cannot know in advance which port the OS will hand it.
+ *
+ * No prefix matching, no wildcard, no "same origin is close enough": every
+ * one of those has a published attack where the code lands on a URL the
+ * attacker controls.
+ */
+export declare function redirectUriMatches(candidate: string, registered: readonly string[]): boolean;
+/** Credentials as they arrived, from either place the spec allows. */
+export interface ClientCredentials {
+    clientId?: string;
+    clientSecret?: string;
+    /**
+     * WHERE they came from.
+     *
+     * A client registers one authentication method and must use that one: a
+     * client declared `client_secret_basic` sending its secret in the body is
+     * either misconfigured or being replayed by something that could only read
+     * the body. Accepting both makes the registered method decorative.
+     */
+    method?: ClientAuthMethod;
+    /** The raw `Authorization` header, if there was one. */
+    authorization?: string;
+}
+/**
+ * Read `client_id` / `client_secret` out of a request.
+ *
+ * A client MUST NOT use more than one authentication method in a single
+ * request (§2.4): sending both Basic and body credentials is a sign of a
+ * confused proxy or of an attempt to have one of them ignored, so it is
+ * refused rather than resolved by precedence.
+ */
+export declare function readCredentials(input: {
+    authorization?: string;
+    body: Record<string, unknown>;
+}): ClientCredentials;
+/**
+ * Authenticate a client for the token endpoint.
+ *
+ * Every failure answers `invalid_client` with no detail — "no such client",
+ * "wrong secret" and "that client has no secret" are the same sentence to the
+ * caller, because telling them apart is how a client list gets enumerated.
+ */
+export declare function authenticateClient(credentials: ClientCredentials, load: (id: string) => Promise<Client | null>): Promise<Client>;
+/** Is this grant one the client was registered for? */
+export declare function assertGrantAllowed(client: Client, grant: GrantType): void;
+/**
+ * Narrow a requested scope against what the client may ever have.
+ *
+ * Absent, the request gets the client's registered set — never "everything".
+ * A scope the client was not registered for is refused rather than dropped:
+ * silently granting less than asked is how a client ends up believing it has
+ * a permission it does not.
+ */
+export declare function resolveScopes(requested: string | undefined, client: Client): string[];
+//# sourceMappingURL=clients.d.ts.map

package/dist/clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../src/clients.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CA2BT;AAMD,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B,GAAG,iBAAiB,CA4BpB;AAgCD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACvC,WAAW,EAAE,iBAAiB,EAC9B,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAC1C,OAAO,CAAC,MAAM,CAAC,CAoCjB;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAMzE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,GACZ,MAAM,EAAE,CAaV"}