@cauthyhq/node 0.0.0 → 1.0.0

package/dist/cauthy-ClP5orP4.d.mts

@@ -0,0 +1,1035 @@
+import { K as KeyStore, P as PactKeys } from './keys-D5k0omTb.mjs';
+import { JWTVerifyGetKey, JWK } from 'jose';
+import { CauthyTheme } from './theme.mjs';
+
+/** What createCauthy is given to run by contract. */
+interface ContractOptions {
+    /** The context graph, as `cauthy contracts pull` writes it (contracts/graph.json). */
+    graph: unknown;
+    /** This application's system in the graph: `"acme-crm"`. */
+    system: string;
+    /** The link to read, when the system has more than one with Cauthy. */
+    link?: string;
+    /** Cauthy's system in the graph. Default: `"cauthy"`. */
+    provider?: string;
+}
+/** What an application reads of its contract. */
+interface ResolvedContract {
+    system: string;
+    link: string;
+    /** Cauthy's public address. */
+    issuer: string;
+    /** The workspace's id, and its slug (what the application's own screens send). */
+    tenantId: string;
+    tenant: string;
+    /** The public client people sign in with: `pact.<link>`. */
+    clientId: string;
+    /** Where people may return after signing in. */
+    redirectUris: string[];
+    /** Whether Cauthy asks the system's proof on the code exchange now (`systemProof` is `required`). */
+    requireSystemProof: boolean;
+    /** How the link asks for the proof: never, from the first proved sign-in on (`auto`), or always. */
+    systemProof: 'off' | 'auto' | 'required';
+    /** Whether Cauthy issues no token through this link before the address is confirmed. */
+    requireVerifiedEmail: boolean;
+    /** Whether the link lets its people ask to stay signed in. */
+    persistentSessions: boolean;
+    /** The system's own client, when the link gives it one: `pact.<link>.service`. */
+    serviceClientId?: string;
+    /** Where the system publishes its keys, and the path of that address. */
+    jwksUrl?: string;
+    jwksPath?: string;
+    /** Where the system receives Cauthy's events, when it says. */
+    eventsUrl?: string;
+}
+/**
+ * The variables of the standard mode. With a contract none may be set: two
+ * sources of the same thing, one silently winning, is how a system ends up
+ * signing people in through a client nobody meant.
+ */
+declare const STANDARD_VARIABLES: readonly ["CAUTHY_ISSUER", "CAUTHY_CLIENT_ID", "CAUTHY_CLIENT_SECRET", "CAUTHY_SECRET", "CAUTHY_SYSTEM", "CAUTHY_TENANT", "CAUTHY_SYSTEM_KEY", "CAUTHY_SYSTEM_KEY_ID"];
+/** Refuses to run by contract with a variable of the standard mode set: names it. */
+declare function failClosed(environment: Record<string, string | undefined> | undefined): void;
+/** Reads what the graph says of the system's link with Cauthy. */
+declare function readContract(options: ContractOptions): ResolvedContract;
+/** One difference between a contract and what Cauthy holds. */
+interface PactItem {
+    kind: 'client' | 'redirect_uri' | 'grant_type' | 'role' | 'organization' | 'require_system_proof' | 'persistent_sessions' | 'jwks_url';
+    client_id?: string;
+    value: string;
+    detail?: string;
+}
+/** How the system stands against its contract, as Cauthy checks it (GET /v1/pact/status). Moments are UTC. */
+interface PactStatus {
+    system: string;
+    tenant_id: string;
+    checked_at: string;
+    /** When Cauthy's daily reconciliation last checked it; null before the first. */
+    reconciled_at: string | null;
+    in_step: boolean;
+    /** In Cauthy, and the contract does not name it. Nothing is ever deleted for it. */
+    outside: PactItem[];
+    /** Named by the contract, and Cauthy does not hold it as it says. */
+    missing: PactItem[];
+    contract: {
+        clients: {
+            client_id: string;
+            link: string;
+            purpose: 'sign_in' | 'service';
+            redirect_uris?: string[];
+            grant_types: string[];
+            require_system_proof?: boolean;
+            jwks_url?: string;
+        }[];
+        roles?: Record<string, string[]>;
+    };
+    held: {
+        clients: Record<string, unknown>[];
+        roles: string[];
+        organizations: Record<string, number>;
+    };
+}
+
+/** Something that happened in Cauthy, as a subscriber is told. Moments are UTC. */
+interface CauthyEvent {
+    /** This delivery's id: the same event delivered again carries the same one. */
+    id: string;
+    /** What happened: "organization.member_added". */
+    type: string;
+    tenantId: string;
+    createdAt: string;
+    /** The person it happened to, when it is about one. */
+    userId?: string;
+    /** Who did it. */
+    actorId?: string;
+    /** What the event says: for an organization, its id, system, external_id, role… */
+    data: Record<string, JsonValue>;
+}
+declare class CauthyWebhookError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+interface VerifyWebhookOptions {
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /**
+     * This endpoint's own public address, exactly as it is registered in Cauthy.
+     * Default: the request's URL, which is right unless a proxy changes it.
+     */
+    url?: string;
+    /** Cauthy's keys. Default: fetched from the issuer and cached. */
+    jwks?: JWTVerifyGetKey;
+    /** The moment to verify at. Default: now. */
+    now?: Date;
+    /**
+     * Where deliveries already taken are remembered, so the same signed
+     * delivery sent twice is refused. Default for verifyWebhook: none;
+     * `auth.webhook` remembers them in memory unless it is given one.
+     */
+    replay?: ReplayStore;
+}
+/**
+ * Remembers what was already taken. `claim` answers true the first time a
+ * key is claimed and false after, until `until` passes.
+ *
+ * A delivery Cauthy sends again after a failure is signed again, and passes:
+ * what is refused is the very same signed delivery arriving twice. Make what
+ * an event does safe to do twice anyway (its `id` stays the same).
+ */
+interface ReplayStore {
+    claim(key: string, until: Date): Promise<boolean>;
+}
+/** Deliveries remembered in this process's memory: enough with one instance. */
+declare function memoryReplayStore(now?: () => number): ReplayStore;
+/**
+ * Verifies a delivery and answers the event it carries. Throws
+ * `CauthyWebhookError` for anything that is not a delivery Cauthy made for
+ * this endpoint just now: answer it 401 and nothing else.
+ */
+declare function verifyWebhook(request: Request, options?: VerifyWebhookOptions): Promise<CauthyEvent>;
+
+/** How an application is set up to sign its people in with Cauthy. */
+interface CauthyOptions {
+    /** Cauthy's public address, e.g. `https://id.example.com`. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The application's OAuth client id. Default: `CAUTHY_CLIENT_ID`. */
+    clientId?: string;
+    /** Its secret, when the client is confidential. Default: `CAUTHY_CLIENT_SECRET`. */
+    clientSecret?: string;
+    /**
+     * The key the session cookie is encrypted with: any string of 32 characters
+     * or more, kept on the server. Default: `CAUTHY_SECRET`.
+     */
+    secret?: string;
+    /**
+     * The system this application is, as its organizations are filed under in
+     * Cauthy (`"acme-crm"`). When set, a session's organizations are that
+     * system's. Default: `CAUTHY_SYSTEM`.
+     */
+    system?: string;
+    /**
+     * The workspace's slug in Cauthy. Needed for the application's own sign-in
+     * screens (`signIn.email`, `signUp.email`…), which sign people in through
+     * the application's server instead of Cauthy's page. Default: `CAUTHY_TENANT`.
+     */
+    tenant?: string;
+    /** Where the routes are mounted. Default: `/api/auth`. */
+    basePath?: string;
+    /**
+     * What happens to a POST without `X-Cauthy-Request: 1` (every POST but
+     * `/logout`). `required`, the default, answers `403 csrf_required`, as
+     * protocol level strict asks. `warn` lets it through and says so once per
+     * process: for the one deploy that moves an application whose browser still
+     * runs cauthy-auth 0.42, which does not send the header. Remove it once the
+     * browser runs cauthy-auth 0.43 or @cauthyhq/js.
+     */
+    requestHeader?: 'required' | 'warn';
+    /**
+     * The audience of the access tokens `auth.verifyToken` accepts: the
+     * deployment's `JWT_AUDIENCE`, which Cauthy requires its operator to set and
+     * has no default for. Default: `CAUTHY_AUDIENCE`.
+     */
+    audience?: string;
+    /**
+     * The workspace's id (a lowercase UUID) for `auth.verifyToken`. By contract
+     * it comes from the link's `tenant_id`; otherwise: this, or `CAUTHY_TENANT_ID`.
+     */
+    tenantId?: string;
+    /**
+     * The application's own public origin (`https://app.example.com`): the
+     * redirect URI, the cookies' `Secure` flag and which forms are its own come
+     * from it. Default: `CAUTHY_BASE_URL`, else the origin of each request, with
+     * the scheme a proxy names in `x-forwarded-proto`. Set it whenever a proxy
+     * also changes the host or the port.
+     */
+    baseURL?: string;
+    /** Where a person lands after signing in, when no `return_to` was asked. Default: `/`. */
+    afterSignIn?: string;
+    /** Where a person lands after signing out. Default: `/`. */
+    afterSignOut?: string;
+    /** Name of the session cookie. Default: `cauthy_session`. */
+    cookieName?: string;
+    /**
+     * A key the application proves who it is with when it acts on its own
+     * (`auth.system`), instead of its secret. Default: `CAUTHY_SYSTEM_KEY` and
+     * `CAUTHY_SYSTEM_KEY_ID`.
+     */
+    systemKey?: SystemKey;
+    /**
+     * The application's own pages for what arrives by mail. A link Cauthy mails
+     * opens the page named here, with a `token` to give back; with none, it
+     * opens Cauthy's own page.
+     *
+     *   signIn         where `<SignIn />` is: a sign-in link opens it
+     *   resetPassword  where `<ResetPassword />` is
+     *   verifyEmail    where `<VerifyEmail />` is
+     *   acceptInvite   where `<AcceptInvite />` is: an invitation opens it
+     *
+     * An invitation sent by `auth.system.members.add` or `auth.system.invite`
+     * opens `acceptInvite` only when the application knows its public origin
+     * (`baseURL`): that call has no request to read it from.
+     */
+    pages?: {
+        signIn?: string;
+        resetPassword?: string;
+        verifyEmail?: string;
+        acceptInvite?: string;
+    };
+    /**
+     * The address of the person a request comes from, passed on to Cauthy so
+     * its limits on attempts count the person and not this server. Default: the
+     * last address in `X-Forwarded-For`, which is the one the proxy in front of
+     * the application wrote. With several proxies, or none, give your own.
+     */
+    clientIp?: (request: Request) => string | undefined;
+    /** `fetch` to reach Cauthy with. Default: the global one. */
+    fetch?: typeof fetch;
+    /**
+     * How long a call to Cauthy may take before it fails, in milliseconds.
+     * `system`: the application's own calls (`auth.system`, and the proof its
+     * sign-ins carry). Default 2000. `request`: the sign-in screens' calls and
+     * the code, refresh and userinfo calls of a session. Default 5000. The
+     * push-approval event stream has no deadline.
+     */
+    timeouts?: {
+        system?: number;
+        request?: number;
+    };
+    /**
+     * Run by contract: the issuer, the workspace, the clients and where the
+     * application's keys are published all come from its link in the network's
+     * context graph, and none of the CAUTHY_* variables may be set. See
+     * "Connect a system by contract".
+     *
+     *   createCauthy({ contract: { graph, system: 'acme-crm' }, keys: postgresKeyStore(query) })
+     */
+    contract?: ContractOptions;
+    /** Where the application keeps its own key, with a contract (@cauthyhq/node/keys). */
+    keys?: KeyStore;
+    /**
+     * The one secret of a contracted application: every key it needs is
+     * derived from it. 32 random bytes or more. Default: `PACT_ROOT_KEY`.
+     */
+    rootKey?: string;
+    /** The root key before the current one, while rotating it. Default: `PACT_ROOT_KEY_PREVIOUS`. */
+    rootKeyPrevious?: string;
+    /**
+     * Where `auth.webhook` remembers the deliveries it took, so one sent twice
+     * is refused. Default: this process's memory. Give a shared one (a table)
+     * when the application runs on several instances.
+     */
+    webhookReplay?: ReplayStore;
+}
+/** The person signed in. Every moment is UTC. */
+interface SessionUser {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    /**
+     * True when the account ran out of time to confirm its address: let it read
+     * and refuse its writes.
+     */
+    restricted: boolean;
+    /** When an unconfirmed address stops being enough (ISO 8601, UTC), if there is a deadline. */
+    emailVerifyBy?: string;
+    /** The language the person reads in ("es", "en-US"), when Cauthy knows it. */
+    locale?: string;
+    /** A guest: a visitor's session before they sign up. No email; `account.upgrade` makes it an account, keeping `id`. */
+    isAnonymous?: boolean;
+}
+/** A value JSON can carry. What crosses from server to browser is typed as this, never `unknown`. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** An organization the person belongs to, with their role in it. */
+interface SessionOrganization {
+    id: string;
+    system: string;
+    name: string;
+    kind: string;
+    externalId?: string;
+    role: string;
+    /** What the system keeps about the organization, as it filed it in Cauthy. */
+    metadata: Record<string, JsonValue>;
+    /**
+     * What the person may do here, as "resource:action" entries ("*" is any):
+     * their role's permissions, what it inherits, and anything given to them
+     * apart from it. Absent when the system keeps no catalog of roles in Cauthy.
+     * Check with `can(organization, resource, action)`.
+     */
+    permissions?: string[];
+    /** What the person is denied here, whatever else allows it. */
+    denied?: string[];
+    /**
+     * Permissions that hold only when their condition does (an amount under a
+     * limit, the person's own records…). They are in neither list above: `can`
+     * answers no for them, and `auth.check` asks Cauthy. Present, maybe empty,
+     * whenever `permissions` is.
+     */
+    conditional?: ConditionalPermission[];
+}
+/** A permission with a condition: Cauthy decides it per question (`auth.check`). */
+interface ConditionalPermission {
+    resource: string;
+    action: string;
+    effect: 'allow' | 'deny';
+}
+/** What to ask Cauthy about: an action on a resource, with what the conditions read of it. */
+interface CheckQuestion {
+    resource: string;
+    action: string;
+    /** What a condition reads as `resource.attrs`: `{ amount: 500 }`. */
+    attributes?: Record<string, unknown>;
+    /** The record's id, as a condition reads it (`resource.id`). */
+    resourceId?: string;
+    /** Whose the record is (`resource.owner_id`): `resource.owner_id == subject.id`. */
+    ownerId?: string;
+}
+/** An organization, by its id or as the session has it. */
+type OrganizationRef = string | {
+    id: string;
+};
+/** The rule that decided a check. */
+interface CheckRule {
+    /** A permission of the person's role, or an exception given to the person. */
+    source: 'role' | 'exception';
+    /** The role, when `source` is `role`. */
+    role?: string;
+    kind: string;
+    resource: string;
+    action: string;
+    effect: 'allow' | 'deny';
+    condition?: string;
+}
+/** Cauthy's answer to a check. */
+interface CheckResult {
+    allowed: boolean;
+    /** Why, in words: "allowed by role accountant: invoices:approve". */
+    reason: string;
+    /** The rule that decided; absent when none did (nothing allows it). */
+    rule?: CheckRule;
+}
+/** A signed-in person, as the server sees them. */
+interface Session {
+    user: SessionUser;
+    /** The Cauthy tenant the account is of. */
+    tenantId: string;
+    /** The roles the account holds in that tenant. */
+    roles: string[];
+    /**
+     * Cauthy's access token for this person: send it as `Authorization: Bearer`
+     * to another service that verifies Cauthy's tokens. Never give it to the browser.
+     */
+    accessToken: string;
+    /** When the access token expires and the session is checked with Cauthy again (ISO 8601, UTC). */
+    expiresAt: string;
+}
+/** What the browser is told of a session: who, and their organizations — never a token. */
+interface PublicSession {
+    user: SessionUser;
+    tenantId: string;
+    roles: string[];
+    organizations: SessionOrganization[];
+    expiresAt: string;
+}
+/** Why there is no session. */
+type SessionStatus = 'authenticated' | 'unauthenticated' | 'expired';
+declare class CauthyConfigError extends Error {
+    constructor(message: string);
+}
+
+/** The part of an organization that says what its member may do. */
+interface Permitted {
+    /** "resource:action" entries the person is allowed; "*" is any. Absent when the system keeps no catalog in Cauthy. */
+    permissions?: string[];
+    /** Entries the person is denied whatever else allows them. */
+    denied?: string[];
+    /** Permissions with a condition: in neither list, so `can` never counts them. Ask with `auth.check`. */
+    conditional?: ConditionalPermission[];
+}
+/**
+ * Whether the person may do an action on a resource in an organization:
+ * allowed by some entry, and denied by none. A denial wins.
+ *
+ * An organization of a system that keeps no catalog in Cauthy carries no
+ * permissions, and the answer is `false`: decide by its `role` instead.
+ *
+ * A permission with a condition (`organization.conditional`) is not in the
+ * lists, so `can` answers `false` for what only it allows: the condition reads
+ * the record at hand, which only Cauthy can weigh. Ask with `auth.check`
+ * (`organizations.check` in the browser).
+ *
+ *   if (!can(organization, 'invoicing', 'write')) return forbidden()
+ */
+declare function can(organization: Permitted | null | undefined, resource: string, action: string): boolean;
+/** Something a role may do: an action on a resource, in organizations of a kind ("*", the default, is every kind). */
+interface PolicyPermission {
+    kind?: string;
+    resource: string;
+    action: string;
+    /**
+     * When it holds, in CEL: `resource.attrs.amount <= 1000000`. A permission
+     * with one is decided by Cauthy per question (`auth.check`), never by `can`.
+     */
+    condition?: string;
+}
+/** The type of an attribute a condition may read: `list` is any JSON array. */
+type AttributeType = 'string' | 'number' | 'bool' | 'list';
+/** A resource of a system's catalog: the actions done on it and the attributes its conditions read. */
+interface CatalogResource {
+    resource: string;
+    description?: string;
+    actions: string[];
+    /** Name → type, as `resource.attrs.<name>` in a condition. */
+    attributes?: Record<string, AttributeType>;
+}
+interface PolicyRole {
+    role: string;
+    name?: string;
+    description?: string;
+    /** Roles whose permissions this one has as well. */
+    inherits?: string[];
+    permissions?: PolicyPermission[];
+}
+type PermissionShape = {
+    readonly kind?: string;
+    readonly resource: string;
+    readonly action: string;
+    readonly condition?: string;
+};
+/** A role as `definePolicy` reads it: any `PolicyRole`, kept as written. */
+type RoleShape = {
+    readonly role: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly inherits?: readonly string[];
+    readonly permissions?: readonly PermissionShape[];
+};
+/** A resource as `definePolicy` reads it: any `CatalogResource`, kept as written. */
+type ResourceShape = {
+    readonly resource: string;
+    readonly description?: string;
+    readonly actions: readonly string[];
+    readonly attributes?: {
+        readonly [name: string]: AttributeType;
+    };
+};
+type Named<S extends string> = S extends '*' ? string : S;
+type PermissionsIn<R> = R extends {
+    readonly permissions: readonly (infer P)[];
+} ? P extends {
+    readonly resource: infer Res extends string;
+    readonly action: infer Act extends string;
+} ? `${Named<Res>}:${Named<Act>}` : never : never;
+type ValueOf<T> = T extends 'string' ? string : T extends 'number' ? number : T extends 'bool' ? boolean : T extends 'list' ? unknown[] : never;
+/** What a check may say about one declared resource. */
+type QuestionAbout<E> = E extends {
+    readonly resource: infer R extends string;
+    readonly actions: readonly (infer A extends string)[];
+} ? {
+    resource: R;
+    action: A;
+    attributes?: E extends {
+        readonly attributes: infer T;
+    } ? {
+        [K in keyof T]?: ValueOf<T[K]>;
+    } : Record<string, never>;
+    resourceId?: string;
+    ownerId?: string;
+} : never;
+/**
+ * What a role of a catalog that declares its resources may name: a declared
+ * resource with one of its actions, or "*", or one of Cauthy's own powers.
+ */
+type PermissionFor<C extends readonly ResourceShape[]> = {
+    readonly kind?: string;
+    readonly condition?: string;
+} & ((C[number] extends infer E ? E extends {
+    readonly resource: infer R extends string;
+    readonly actions: readonly (infer A extends string)[];
+} ? {
+    readonly resource: R;
+    readonly action: A | '*';
+} : never : never) | {
+    readonly resource: '*';
+    readonly action: string;
+} | {
+    readonly resource: `cauthy:${string}`;
+    readonly action: string;
+});
+type RoleFor<C extends readonly ResourceShape[]> = Omit<RoleShape, 'permissions'> & {
+    readonly permissions?: readonly PermissionFor<C>[];
+};
+/** The roles a catalog names: `RoleOf<typeof policy>`. */
+type RoleOf<P> = P extends Policy<infer R, any, any> ? R : never;
+/** The "resource:action" permissions a catalog names: `PermissionOf<typeof policy>`. */
+type PermissionOf<P> = P extends Policy<any, infer X, any> ? X : never;
+/** What a check about this catalog may ask: `CheckOf<typeof policy>`. Any resource when it declares none. */
+type CheckOf<P> = P extends Policy<any, any, infer Q> ? Q : never;
+/** The fields of a question: whatever else the asker takes (the organization, the person) passes through. */
+type QuestionKeys = keyof CheckQuestion;
+interface Policy<Role extends string = string, Permission extends string = string, Question extends CheckQuestion = CheckQuestion> {
+    /** The catalog as Cauthy takes it: `pushPolicy({ roles: policy.roles })`. */
+    roles: PolicyRole[];
+    /** The resources the system declares, as Cauthy takes them; empty when it declares none. */
+    catalog: CatalogResource[];
+    /** Every role's name. */
+    roleNames: Role[];
+    /** Every permission some role has, as "resource:action". */
+    permissions: Permission[];
+    /**
+     * Whether the person may do this in the organization: `can(org, 'ledger:write')`.
+     * It reads what Cauthy sent with the session, so a catalog edited in Cauthy
+     * since this file was written is still what decides. A permission with a
+     * condition is not there: ask with `check`.
+     */
+    can(organization: Permitted | null | undefined, permission: Permission): boolean;
+    /** Whether the person's role in the organization is one of these. */
+    hasRole(organization: {
+        role: string;
+    } | null | undefined, ...roles: Role[]): boolean;
+    /**
+     * What a role may do by this catalog, with what it inherits: for showing a
+     * role, never for deciding about a person (their exceptions are not here).
+     */
+    permissionsOf(role: Role): Permission[];
+    /**
+     * Asks Cauthy, with the resource, action and attributes typed by the
+     * catalog. Give it whoever asks: the server's `auth` with the request,
+     * the browser's `organizations`, or the application's `system`.
+     *
+     *   await policy.check(auth, request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+     *   await policy.check(auth.system, { organizationId, userId, resource: 'invoices', action: 'read' })
+     */
+    check<I extends CheckQuestion>(asker: {
+        check(input: I): Promise<CheckResult>;
+    }, input: Omit<I, QuestionKeys> & Question): Promise<CheckResult>;
+    check<R, I extends CheckQuestion>(asker: {
+        check(request: R, input: I): Promise<CheckResult>;
+    }, request: R, input: Omit<I, QuestionKeys> & Question): Promise<CheckResult>;
+}
+/** A catalog with its resources declared, for `definePolicy`. */
+interface PolicyDefinition<C extends readonly ResourceShape[], T extends readonly RoleShape[]> {
+    catalog: C;
+    roles: T;
+}
+/** Gives a catalog of roles its types. See the top of this section. */
+declare function definePolicy<const T extends readonly RoleShape[]>(roles: T): Policy<T[number]['role'], PermissionsIn<T[number]>>;
+/** Gives a catalog of resources and roles its types: a role names only what the catalog declares. */
+declare function definePolicy<const C extends readonly ResourceShape[], const T extends readonly RoleFor<C>[]>(definition: PolicyDefinition<C, T>): Policy<T[number]['role'], PermissionsIn<T[number]>, QuestionAbout<C[number]>>;
+/** A system's policy as Cauthy has it: the resources it declares (maybe none) and its roles. */
+interface SystemPolicy {
+    catalog: CatalogResource[];
+    roles: PolicyRole[];
+}
+/**
+ * A TypeScript module that defines the catalog given, for `pullPolicy` to
+ * write: the application's types then come from the catalog
+ * Cauthy has. With resources declared it is `definePolicy({ catalog, roles })`;
+ * without, the list of roles alone, as it always was.
+ */
+declare function policySource(system: string, read: PolicyRole[] | {
+    catalog?: CatalogResource[];
+    roles: PolicyRole[];
+}): string;
+/** Reads a system's catalog of roles from Cauthy, with a personal access token. */
+declare function pullPolicy(o?: Omit<PushPolicyOptions, 'roles'>): Promise<PolicyRole[]>;
+/** Reads the resources a system declares (empty when it declares none), with a personal access token. */
+declare function pullCatalog(o?: Omit<PushPolicyOptions, 'roles'>): Promise<CatalogResource[]>;
+interface PushPolicyOptions {
+    /** The system whose catalog this is. Default: `CAUTHY_SYSTEM`. */
+    system?: string;
+    roles: PolicyRole[];
+    /**
+     * The resources the system declares. Given, they are sent before the roles,
+     * which Cauthy then checks against them; left out, the catalog Cauthy has
+     * stays as it is.
+     */
+    catalog?: CatalogResource[];
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The workspace's slug. Default: `CAUTHY_TENANT`. */
+    tenant?: string;
+    /**
+     * A personal access token: `organizations:manage` reads, and changing a
+     * policy or a catalog takes `systems:policy`. Default: `CAUTHY_TOKEN`.
+     */
+    token?: string;
+    fetch?: typeof fetch;
+    /** How long the call may take, in milliseconds, before it fails with a `TimeoutError`. Default: 5000. */
+    timeoutMs?: number;
+}
+/**
+ * Gives Cauthy a system's catalog of roles, replacing the one it has. It is
+ * the way to load a first catalog from what a system already had; from then on
+ * the catalog is Cauthy's, edited in its dashboard, and pushing again would
+ * overwrite what was edited there. With `catalog` the declared resources go
+ * first: the roles are checked against them.
+ */
+declare function pushPolicy(o: PushPolicyOptions): Promise<void>;
+/**
+ * Gives Cauthy the resources a system declares, replacing the ones it has.
+ * Cauthy refuses (`catalog_in_use`) to drop a resource or an action the
+ * policy still names.
+ */
+declare function pushCatalog(o: Omit<PushPolicyOptions, 'roles' | 'catalog'> & {
+    resources: CatalogResource[];
+}): Promise<CatalogResource[]>;
+
+/** The key an application signs its assertions with. */
+interface SystemKey {
+    /** The private key: PKCS#8 PEM, or a JWK (as an object or its JSON). RSA, for RS256. */
+    privateKey: string | JWK;
+    /** The id the public key is published under (`kid`). */
+    keyId: string;
+    /**
+     * The client the key belongs to, when it is not the one people sign in
+     * with: a public sign-in client has no key of its own, and the system's
+     * identity is a confidential client beside it. Default: the client id.
+     */
+    clientId?: string;
+}
+interface SystemOptions {
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The application's client id. Default: `CAUTHY_CLIENT_ID`. */
+    clientId?: string;
+    /** Its secret. Default: `CAUTHY_CLIENT_SECRET`. Not needed with `key`. */
+    clientSecret?: string;
+    /**
+     * The key to prove who the application is with, instead of the secret.
+     * Default: `CAUTHY_SYSTEM_KEY` (the private key) and `CAUTHY_SYSTEM_KEY_ID`.
+     */
+    key?: SystemKey;
+    /** The application's system, which `check` asks about. Default: `CAUTHY_SYSTEM`. */
+    system?: string;
+    /**
+     * The application's own page for accepting an invitation, as an absolute
+     * address (`https://app.example.com/accept-invite`, where `<AcceptInvite />`
+     * is). The invitations `members.add` and `invite` send open it; without it,
+     * they open Cauthy's own page. Cauthy follows it only on an origin the
+     * client registered to be sent back to. Default: `CAUTHY_ACCEPT_INVITE_URL`.
+     */
+    acceptInviteUrl?: string;
+    /**
+     * The application's own keys, kept in its database (contract mode): it
+     * signs with the newest and publishes them. Takes the place of `key`.
+     */
+    keys?: PactKeys;
+    /** The client the keys prove: the system's own, beside the sign-in client. */
+    keysClientId?: string;
+    fetch?: typeof fetch;
+    /** How long a call to Cauthy may take before it fails with `503 unavailable`, in milliseconds. Default: 2000. */
+    timeoutMs?: number;
+}
+/** Cauthy refused a request of the application's own. */
+declare class CauthyApiError extends Error {
+    readonly status: number;
+    /** Cauthy's code for what went wrong: `organization_not_found`, `other_system`, `outside_system_scope`, `member_exists`… */
+    readonly code: string;
+    constructor(status: number, 
+    /** Cauthy's code for what went wrong: `organization_not_found`, `other_system`, `outside_system_scope`, `member_exists`… */
+    code: string, message: string);
+}
+/** An organization of the application's system. Every moment is UTC. */
+interface Organization {
+    id: string;
+    system: string;
+    name: string;
+    kind: string;
+    /** The id the application knows it by. */
+    externalId?: string;
+    status: 'active' | 'archived';
+    metadata: Record<string, JsonValue>;
+    members: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface OrganizationMember {
+    userId: string;
+    email: string;
+    name: string;
+    /** The account's status: a disabled member is still listed. */
+    status: string;
+    role: string;
+    /** True when the address had no account: one was made and invited. */
+    invited?: boolean;
+}
+/** Who to add: an account by its id, or anybody by their address (invited when new). */
+type NewMember = {
+    role: string;
+    name?: string;
+    locale?: string;
+    /**
+     * Adds and nothing else (the default): a person who already belongs keeps
+     * their role, and the call throws `CauthyApiError` with code
+     * `member_exists` (409). `false` sets the role of whoever is already
+     * there, as `setRole` does.
+     */
+    onlyNew?: boolean;
+} & ({
+    userId: string;
+    email?: undefined;
+} | {
+    email: string;
+    userId?: undefined;
+});
+interface CauthySystem {
+    /** The application's own token, asked for when needed and kept until it is about to run out. */
+    token(): Promise<string>;
+    /** Any route the application's token may call; answers what Cauthy put under `data`. */
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    organizations: {
+        list(query?: {
+            q?: string;
+            status?: 'active' | 'archived';
+            limit?: number;
+            offset?: number;
+        }): Promise<{
+            items: Organization[];
+            total: number;
+        }>;
+        create(input: {
+            name: string;
+            kind?: string;
+            externalId?: string;
+            metadata?: Record<string, JsonValue>;
+        }): Promise<Organization>;
+        get(id: string): Promise<Organization>;
+        update(id: string, patch: {
+            name?: string;
+            kind?: string;
+            status?: 'active' | 'archived';
+            metadata?: Record<string, JsonValue>;
+        }): Promise<Organization>;
+        /** Removes the organization and every membership of it, for good. */
+        remove(id: string): Promise<void>;
+    };
+    members: {
+        list(organizationId: string): Promise<OrganizationMember[]>;
+        /** Adds a person; one who already belongs throws `member_exists` unless `onlyNew: false`. */
+        add(organizationId: string, member: NewMember): Promise<OrganizationMember>;
+        setRole(organizationId: string, userId: string, role: string): Promise<OrganizationMember>;
+        remove(organizationId: string, userId: string): Promise<void>;
+    };
+    /** Invites a person who has no account yet; answers the account made for them. */
+    invite(person: {
+        email: string;
+        name?: string;
+        locale?: string;
+    }): Promise<{
+        id: string;
+        email: string;
+    }>;
+    /**
+     * How the application looks on Cauthy's pages, read. It is decided in
+     * Cauthy's dashboard, by a person: an application never changes it.
+     */
+    theme: {
+        get(clientId?: string): Promise<CauthyTheme>;
+    };
+    /** The catalog of roles of one of the application's systems, as Cauthy has it. */
+    policy: {
+        get(system: string): Promise<PolicyRole[]>;
+    };
+    /**
+     * The resources one of the application's systems declares, with their
+     * actions and the attributes conditions read; empty when it declares none.
+     */
+    catalog: {
+        get(system: string): Promise<CatalogResource[]>;
+        /** Replaces them. Cauthy refuses (`catalog_in_use`) to drop one the policy still names. */
+        set(system: string, resources: CatalogResource[]): Promise<CatalogResource[]>;
+    };
+    /**
+     * Asks Cauthy whether a member of one of the system's organizations may do
+     * an action on a resource, conditions weighed. A person who is not a member
+     * is a no; an organization of another system throws (`organization_not_found`).
+     */
+    check(question: CheckQuestion & {
+        organizationId: string;
+        userId: string;
+        system?: string;
+    }): Promise<CheckResult>;
+    /** The public half of `key`, to serve at the address Cauthy was given (`jwks_uri`). Empty with a secret. */
+    publicJwks(): Promise<{
+        keys: JWK[];
+    }>;
+}
+declare function createSystem(given?: SystemOptions): CauthySystem;
+
+/** Who a verified access token belongs to. */
+interface TokenIdentity {
+    /** The person. For a system's own token, the client it identifies as. */
+    userId: string;
+    tenantId: string;
+    email?: string;
+    /** What the token says of the address, when it says (a boolean; absent otherwise). */
+    emailVerified?: boolean;
+    roles: string[];
+    /** Set when the token is a system's own and not a person's (only with `allowSystem`). */
+    system?: string;
+    /** Set when the token is a guest's (only with `allowAnonymous`). */
+    anonymous?: true;
+    /** UTC, ISO 8601. */
+    expiresAt: string;
+    /** The token as it arrived, to pass on. */
+    token: string;
+}
+/** Why a token was refused: the closed list of verification/rules.md, and `no_token` when none was given. */
+type TokenRefusal = 'no_token' | 'too_large' | 'malformed' | 'alg_not_allowed' | 'unsupported_header' | 'missing_kid' | 'unknown_kid' | 'weak_key' | 'bad_signature' | 'missing_claim' | 'invalid_claim' | 'wrong_issuer' | 'wrong_audience' | 'expired' | 'not_yet_valid' | 'issued_in_future' | 'wrong_tenant' | 'system_token' | 'anonymous_token';
+/**
+ * Cauthy's keys could not be fetched (or are not a key set): the token may be
+ * good, and the application cannot tell. Answer 503, not 401. It is not a
+ * `CauthyTokenError`: it says nothing about the token.
+ */
+declare class CauthyUnavailableError extends Error {
+    constructor(detail: string);
+}
+declare class CauthyTokenError extends Error {
+    readonly reason: TokenRefusal;
+    readonly detail?: string | undefined;
+    constructor(reason: TokenRefusal, detail?: string | undefined);
+}
+interface VerifyTokenOptions {
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /**
+     * Further issuers a token may name, e.g. a workspace's custom domain. The
+     * keys always come from `issuer`. Default: none.
+     */
+    issuers?: string[];
+    /** The audience the tokens must carry. Required: this or `CAUTHY_AUDIENCE`. */
+    audience?: string;
+    /** The workspace's id, a lowercase UUID. Required: this or `CAUTHY_TENANT_ID`. */
+    tenantId?: string;
+    /** Cauthy's keys. Default: fetched from the issuer and cached (see `remoteKeys`). */
+    jwks?: JWTVerifyGetKey;
+    /** The fetch to get the keys with. Default: the global one. */
+    fetch?: typeof fetch;
+    /** The moment to verify at. Default: now. */
+    now?: Date;
+    /** Clock tolerance in seconds, 0 to 60. Default: 30. */
+    leeway?: number;
+    /**
+     * Accept a system's own token (a `sys` claim) too: for an endpoint another
+     * system calls. Default: false, so a system's token never stands for a
+     * person (rule R13 of the spec's verification/rules.md).
+     */
+    allowSystem?: boolean;
+    /** Accept a guest's token (`anon: true`). Default: false (rule R14). */
+    allowAnonymous?: boolean;
+}
+/**
+ * Cauthy's published keys (K1 to K5 of verification/rules.md): fetched with a
+ * GET that follows no redirect, within 5 seconds, from `<issuer>/.well-known/jwks.json`;
+ * only a 200 of at most 64 KiB counts. Kept for the answer's max-age (at most
+ * an hour and at least a minute, 5 minutes when it names none); a `kid` the set lacks fetches again
+ * only if the last fetch is older than 30 seconds; one fetch at a time; a
+ * failed fetch keeps the last good set, and with none it is
+ * `CauthyUnavailableError`.
+ */
+declare function remoteKeys(issuer: string, fetchKeys?: typeof fetch): JWTVerifyGetKey;
+/**
+ * A verifier for access tokens, configured once. Refuses to be made without
+ * an issuer, an audience and a workspace: a verifier that checks none of
+ * them would accept a token of any other application or workspace.
+ */
+declare function createTokenVerifier(options?: VerifyTokenOptions): (from: string | Request | Headers) => Promise<TokenIdentity>;
+/**
+ * Verifies an access token (or the `Authorization: Bearer` of a request) and
+ * answers who it belongs to, by the rules of the spec's verification/rules.md.
+ * Needs an issuer, an audience and a workspace (see `createTokenVerifier`,
+ * which checks them once, at startup).
+ */
+declare function verifyToken(from: string | Request | Headers, options?: VerifyTokenOptions): Promise<TokenIdentity>;
+
+/**
+ * Where the probes go: the running application's origin
+ * (`'http://localhost:3000'`), or a function that serves a request in
+ * process (Hono's `app.fetch`, `checkFastifyMount` for Fastify).
+ */
+type MountTarget = string | ((request: Request) => Response | Promise<Response>);
+
+/** What `resolve` answers: who is there, and the cookies that must go back. */
+interface Resolved {
+    session: Session | null;
+    status: SessionStatus;
+    /** `Set-Cookie` values to send with the response. Empty when nothing changed. */
+    cookies: string[];
+}
+interface Cauthy {
+    /** Serves the routes under `basePath`: login, callback, session, refresh, logout, account. */
+    handler(request: Request): Promise<Response>;
+    /**
+     * Checks that this handler is what answers under `basePath` in the running
+     * application, and throws `CauthyConfigError` naming the route when another
+     * one does. Call it once at startup: with the origin after the server
+     * listens (`'http://localhost:3000'`), or with a function that serves a
+     * request in process (Hono's `app.fetch`; `checkFastifyMount` for
+     * Fastify). Nothing it sends reaches Cauthy.
+     */
+    checkMount(target: MountTarget): Promise<void>;
+    /**
+     * Who is signed in, or null.
+     *
+     * Give it the response's headers and a session that needs renewing is
+     * renewed on the spot, its new cookie added to them. Without them an
+     * expired session reads as null (see `status`): renewing changes the
+     * cookie, and a cookie nobody sends back is a session lost.
+     */
+    getSession(request: Request, responseHeaders?: Headers): Promise<Session | null>;
+    /** Whether somebody is signed in, nobody is, or the session must be renewed first. */
+    status(request: Request): Promise<SessionStatus>;
+    /**
+     * The session, renewed when it has to be, and the cookies to send back.
+     * The caller MUST send `cookies` with its response.
+     */
+    resolve(request: Request): Promise<Resolved>;
+    /**
+     * For a route only a signed-in person may see: the session, or the response
+     * to give instead — a redirect to sign in (or to renew) for a page, a 401
+     * for anything else.
+     */
+    protect(request: Request): Promise<{
+        session: Session;
+        response?: undefined;
+    } | {
+        session?: undefined;
+        response: Response;
+    }>;
+    /** The organizations the person belongs to (of `system`, when set), with their role in each. */
+    organizations(session: Session): Promise<SessionOrganization[]>;
+    /**
+     * Asks Cauthy whether the signed-in person may do an action on a resource
+     * in an organization, with what its conditions read (`attributes`, whose
+     * the record is). It is how a permission with a condition is decided —
+     * `can` never counts those — and it decides any other the same way.
+     *
+     *   const r = await auth.check(request, { organization, resource: 'invoices', action: 'approve', attributes: { amount: 500 } })
+     *   if (!r.allowed) return forbidden(r.reason)
+     *
+     * Nobody signed in, an organization the person is not in, or a disabled
+     * account answer `allowed: false`. A request whose session must be renewed
+     * first reads as nobody signed in: give it the `Session` from
+     * `getSession(request, responseHeaders)` instead. Throws `CauthyApiError`
+     * when Cauthy refuses the question itself (a malformed one) or cannot be reached.
+     */
+    check(who: Request | Session, question: CheckQuestion & {
+        organization: OrganizationRef;
+    }): Promise<CheckResult>;
+    /**
+     * Verifies a webhook delivery from Cauthy and answers the event it carries;
+     * throws `CauthyWebhookError` for anything else. No secret is involved: the
+     * delivery is signed with Cauthy's own key.
+     */
+    webhook(request: Request, options?: Pick<VerifyWebhookOptions, 'jwks' | 'now' | 'url'>): Promise<CauthyEvent>;
+    /**
+     * Verifies a Cauthy access token (or a request's `Authorization: Bearer`) for
+     * an API of this application: `verifyToken` with this instance's issuer, its
+     * workspace (by contract, the link's `tenant_id`; otherwise `tenantId` or
+     * `CAUTHY_TENANT_ID`) and its audience (`audience` or `CAUTHY_AUDIENCE`).
+     */
+    verifyToken(from: string | Request | Headers, options?: Partial<VerifyTokenOptions>): Promise<TokenIdentity>;
+    /** The same, built once: throws `CauthyConfigError` now if the audience or the workspace is missing. */
+    tokenVerifier(options?: Partial<VerifyTokenOptions>): (from: string | Request | Headers) => Promise<TokenIdentity>;
+    /**
+     * The application acting on its own, with no person's token: its
+     * organizations, their members, invitations. Needs the client's secret, or
+     * `systemKey`.
+     */
+    system: CauthySystem;
+    /**
+     * The application's contract, when it runs by one: what its link says,
+     * its own keys, and how it stands against its contract in Cauthy.
+     */
+    pact?: CauthyPact;
+    /** What the browser may be told of a session. */
+    toPublic(session: Session): Promise<PublicSession>;
+    /** Paths of this application that start a sign-in, a sign-out, or open the account page. */
+    urls: {
+        signIn(returnTo?: string): string;
+        signOut(): string;
+        account(returnTo?: string): string;
+        session: string;
+    };
+    options: Readonly<Required<Pick<CauthyOptions, 'issuer' | 'clientId' | 'basePath' | 'afterSignIn' | 'afterSignOut' | 'cookieName'>>>;
+}
+/** A contracted application's view of its contract (`auth.pact`). */
+interface CauthyPact {
+    /** What its link in the graph says. */
+    contract: ResolvedContract;
+    /** Its own keys: the one that signs, the ones published, rotating them. */
+    keys: PactKeys;
+    /**
+     * The response for its jwks_url: the published keys. `handler` serves it
+     * at that path too, when the route reaches it.
+     */
+    jwks(): Promise<Response>;
+    /** How it stands against its contract, as Cauthy checks it now. For a health endpoint. */
+    status(): Promise<PactStatus>;
+}
+declare function createCauthy(given?: CauthyOptions): Cauthy;
+
+export { createTokenVerifier as $, type AttributeType as A, type PushPolicyOptions as B, type Cauthy as C, type Resolved as D, type ResolvedContract as E, type RoleOf as F, STANDARD_VARIABLES as G, type SessionOrganization as H, type SessionStatus as I, type JsonValue as J, type SessionUser as K, type SystemKey as L, type MountTarget as M, type NewMember as N, type Organization as O, type PactItem as P, type SystemOptions as Q, type ReplayStore as R, type Session as S, type SystemPolicy as T, type TokenIdentity as U, type TokenRefusal as V, type VerifyTokenOptions as W, type VerifyWebhookOptions as X, can as Y, createCauthy as Z, createSystem as _, type CatalogResource as a, definePolicy as a0, failClosed as a1, memoryReplayStore as a2, policySource as a3, pullCatalog as a4, pullPolicy as a5, pushCatalog as a6, pushPolicy as a7, readContract as a8, remoteKeys as a9, verifyToken as aa, verifyWebhook as ab, CauthyApiError as b, CauthyConfigError as c, type CauthyEvent as d, type CauthyOptions as e, type CauthyPact as f, type CauthySystem as g, CauthyTokenError as h, CauthyUnavailableError as i, CauthyWebhookError as j, type CheckOf as k, type CheckQuestion as l, type CheckResult as m, type CheckRule as n, type ConditionalPermission as o, type ContractOptions as p, type OrganizationMember as q, type OrganizationRef as r, type PactStatus as s, type PermissionOf as t, type Permitted as u, type Policy as v, type PolicyDefinition as w, type PolicyPermission as x, type PolicyRole as y, type PublicSession as z };