cauthy-auth 0.1.0 → 0.3.0

package/README.md

@@ -44,7 +44,18 @@ Built with Stackmyth? Give Cauthy's pages your application's look from its own t
 npx cauthy-auth theme --css node_modules/@stackmyth/core/core.vars.css --css src/styles/brand-theme.css --push
 ```
 
-Register your application in Cauthy with the redirect URI `https://<your app>/api/auth/callback`. `CAUTHY_SECRET` is any string of 32 characters or more: it encrypts the session cookie.
+Connect your application to Cauthy in one step, from Cauthy's dashboard ("Connect a System") or from a terminal. It makes the client, registers `https://<your app>/api/auth/callback`, and prints every variable to set, `CAUTHY_SECRET` included:
+
+```bash
+npx cauthy-auth init --system ledger --app-url https://app.example.com
+```
+
+The same client is your application's own identity: it manages its organizations with no person's token.
+
+```ts
+const org = await auth.system.organizations.create({ name: 'Acme' })
+await auth.system.members.add(org.id, { role: 'owner', email: 'ana@acme.com' })
+```
 
 The full guide is in Cauthy's documentation, under "Auth SDK".
 

package/dist/cauthy-C5_lopMQ.d.ts

@@ -0,0 +1,108 @@
+import { J as JsonValue, S as Session, f as SessionStatus, e as SessionOrganization, c as CauthySystem, P as PublicSession, b as CauthyOptions } from './system-BWLddIt2.js';
+import { JWTVerifyGetKey } from 'jose';
+
+/** 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;
+}
+/**
+ * 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>;
+
+/** 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>;
+    /**
+     * 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[]>;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /** 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'>>>;
+}
+declare function createCauthy(given?: CauthyOptions): Cauthy;
+
+export { type Cauthy as C, type Resolved as R, type VerifyWebhookOptions as V, type CauthyEvent as a, CauthyWebhookError as b, createCauthy as c, verifyWebhook as v };

package/dist/cauthy-mNADGlNl.d.mts

@@ -0,0 +1,108 @@
+import { J as JsonValue, S as Session, f as SessionStatus, e as SessionOrganization, c as CauthySystem, P as PublicSession, b as CauthyOptions } from './system-BWLddIt2.mjs';
+import { JWTVerifyGetKey } from 'jose';
+
+/** 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;
+}
+/**
+ * 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>;
+
+/** 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>;
+    /**
+     * 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[]>;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /** 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'>>>;
+}
+declare function createCauthy(given?: CauthyOptions): Cauthy;
+
+export { type Cauthy as C, type Resolved as R, type VerifyWebhookOptions as V, type CauthyEvent as a, CauthyWebhookError as b, createCauthy as c, verifyWebhook as v };

package/dist/cli.js

@@ -4,6 +4,74 @@
 // src/cli.ts
 var import_node_fs = require("fs");
 
+// src/connect.ts
+function sessionSecret() {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function connectSystem(o) {
+  const env = (n) => typeof process !== "undefined" ? process.env?.[n] : void 0;
+  const issuer = (o.issuer ?? env("CAUTHY_ISSUER") ?? "").replace(/\/+$/, "");
+  const tenant = o.tenant ?? env("CAUTHY_TENANT") ?? "";
+  const token = o.token ?? env("CAUTHY_TOKEN") ?? "";
+  for (const [name, v] of Object.entries({ CAUTHY_ISSUER: issuer, CAUTHY_TENANT: tenant, CAUTHY_TOKEN: token })) {
+    if (v === "") throw new Error(`cauthy-auth: ${name} is required to connect a system`);
+  }
+  const res = await (o.fetch ?? fetch)(`${issuer}/v1/connect`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "x-tenant-key": tenant, "content-type": "application/json" },
+    body: JSON.stringify({
+      system: o.system,
+      app_url: o.appUrl,
+      name: o.name,
+      callback_path: o.callbackPath,
+      events_url: o.eventsUrl,
+      events: o.events,
+      jwks_uri: o.jwksUri
+    })
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !body?.data) {
+    const why = (body?.errors ?? []).map((e) => e.message).filter(Boolean).join("; ") || res.statusText;
+    throw new Error(`cauthy-auth: Cauthy did not connect the system (${res.status}): ${why}`);
+  }
+  const d = body.data;
+  return {
+    system: d.system,
+    clientId: d.client.client_id,
+    clientSecret: d.client_secret,
+    redirectUris: d.client.redirect_uris,
+    webhook: d.webhook,
+    env: { ...d.env, CAUTHY_SECRET: sessionSecret() }
+  };
+}
+function envFile(env) {
+  return Object.entries(env).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
+}
+
+// src/permissions.ts
+async function pushPolicy(o) {
+  const env = (n) => typeof process !== "undefined" ? process.env?.[n] : void 0;
+  const issuer = (o.issuer ?? env("CAUTHY_ISSUER") ?? "").replace(/\/+$/, "");
+  const system = o.system ?? env("CAUTHY_SYSTEM") ?? "";
+  const tenant = o.tenant ?? env("CAUTHY_TENANT") ?? "";
+  const token = o.token ?? env("CAUTHY_TOKEN") ?? "";
+  for (const [name, v] of Object.entries({ CAUTHY_ISSUER: issuer, CAUTHY_SYSTEM: system, CAUTHY_TENANT: tenant, CAUTHY_TOKEN: token })) {
+    if (v === "") throw new Error(`cauthy-auth: ${name} is required to push a policy`);
+  }
+  const res = await (o.fetch ?? fetch)(`${issuer}/v1/systems/${encodeURIComponent(system)}/policy`, {
+    method: "PUT",
+    headers: { authorization: `Bearer ${token}`, "x-tenant-key": tenant, "content-type": "application/json" },
+    body: JSON.stringify({ roles: o.roles })
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    throw new Error(`cauthy-auth: Cauthy refused the policy (${res.status}): ${body?.errors?.[0]?.message ?? res.statusText}`);
+  }
+}
+
 // src/theme.ts
 var MAX_RADIUS = 40;
 function declarations(css) {
@@ -225,7 +293,137 @@ async function pushTheme(o) {
 }
 
 // src/cli.ts
-var HELP = `cauthy-auth theme [options]
+var INIT_HELP = `cauthy-auth init --system <name> --app-url <address> [options]
+
+Connects an application to Cauthy: makes its client, registers where its people
+come back to and where it hears events, and prints the variables to set.
+
+  --system <name>         The system's name: lowercase letters, digits, - or _.
+  --app-url <address>     The application's public address: https://app.example.com,
+                          or http://localhost:3000 while developing.
+  --name <name>           Shown to people on Cauthy's pages. Default: the system's name.
+  --callback-path <path>  Where the application serves the return from a sign-in.
+                          Default: /api/auth/callback.
+  --events-url <address>  An https address of the application that receives
+                          Cauthy's events (verify them with auth.webhook).
+  --jwks-uri <address>    Where the application publishes its keys, to prove
+                          itself with a signature instead of its secret.
+  --write <file>          Append the variables to this file instead of printing
+                          them (they include the client's secret, shown once).
+
+Needs CAUTHY_ISSUER, CAUTHY_TENANT (the workspace's slug) and CAUTHY_TOKEN (a
+personal access token with systems:connect).
+`;
+async function init(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(INIT_HELP);
+    return;
+  }
+  const given = {};
+  const flags = ["--system", "--app-url", "--name", "--callback-path", "--events-url", "--jwks-uri", "--write"];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!flags.includes(arg)) fail(`unknown option ${arg}
+
+${INIT_HELP}`);
+    given[arg] = argv[++i] ?? fail(`${arg} needs a value`);
+  }
+  if (!given["--system"] || !given["--app-url"]) fail("give --system and --app-url\n\n" + INIT_HELP);
+  const done = await connectSystem({
+    system: given["--system"],
+    appUrl: given["--app-url"],
+    name: given["--name"],
+    callbackPath: given["--callback-path"],
+    eventsUrl: given["--events-url"],
+    jwksUri: given["--jwks-uri"]
+  });
+  const vars = envFile(done.env);
+  process.stdout.write(`Connected: the system ${done.system} is the client ${done.clientId}.
+`);
+  process.stdout.write(`  people come back to  ${done.redirectUris.join(", ")}
+`);
+  if (done.webhook) process.stdout.write(`  events are sent to   ${done.webhook.url}
+`);
+  if (given["--write"]) {
+    (0, import_node_fs.appendFileSync)(given["--write"], vars, { mode: 384 });
+    process.stdout.write(`
+The variables were added to ${given["--write"]}. Keep that file out of the repository.
+`);
+  } else {
+    process.stdout.write(`
+Set these where the application runs. The secret is shown this once:
+
+${vars}`);
+  }
+  process.stdout.write(`
+Then, in the application:
+
+  import { createCauthy } from 'cauthy-auth'
+  export const auth = createCauthy()
+
+and serve auth.handler(request) under ${(given["--callback-path"] ?? "/api/auth/callback").replace(/\/callback$/, "")}/*.
+`);
+}
+var POLICY_HELP = `cauthy-auth policy --file <roles.json> [--system <name>] [--push]
+
+Loads a system's catalog of roles into Cauthy from a file:
+
+  { "roles": [ { "role": "accountant", "name": "Accountant", "inherits": ["reader"],
+      "permissions": [ { "resource": "ledger", "action": "write" },
+                       { "kind": "business", "resource": "books.close", "action": "write" } ] } ] }
+
+  --file <file>     The catalog, as JSON.
+  --system <name>   The system it is of. Default: CAUTHY_SYSTEM.
+  --push            Send it to Cauthy, REPLACING the catalog it has. Without it
+                    the catalog is only checked and shown.
+
+Use it to load a first catalog. Afterwards the catalog is Cauthy's, edited in
+its dashboard: pushing again overwrites what was edited there.
+
+To push: CAUTHY_ISSUER, CAUTHY_TENANT (the workspace's slug) and CAUTHY_TOKEN
+(a personal access token with organizations:manage).
+`;
+async function policy(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(POLICY_HELP);
+    return;
+  }
+  let file;
+  let system;
+  let push = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const value = () => argv[++i] ?? fail(`${arg} needs a value`);
+    if (arg === "--file") file = value();
+    else if (arg === "--system") system = value();
+    else if (arg === "--push") push = true;
+    else fail(`unknown option ${arg}
+
+${POLICY_HELP}`);
+  }
+  if (!file) fail("give the catalog with --file\n\n" + POLICY_HELP);
+  let roles;
+  try {
+    const parsed = JSON.parse((0, import_node_fs.readFileSync)(file, "utf8"));
+    const list = Array.isArray(parsed) ? parsed : parsed.roles;
+    if (!Array.isArray(list)) throw new Error('no "roles" list');
+    roles = list;
+  } catch (err) {
+    return fail(`cannot read ${file}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const permissions = roles.reduce((n, r) => n + (r.permissions?.length ?? 0), 0);
+  process.stdout.write(`${roles.length} roles, ${permissions} permissions: ${roles.map((r) => r.role).join(", ")}
+`);
+  if (push) {
+    await pushPolicy({ system, roles });
+    process.stdout.write("Sent to Cauthy: this is now the catalog of the system.\n");
+  } else {
+    process.stdout.write("Not sent. Add --push to give it to Cauthy.\n");
+  }
+}
+var HELP = `cauthy-auth init \u2026     connect an application to Cauthy (cauthy-auth init --help)
+cauthy-auth policy \u2026   load a system's catalog of roles (cauthy-auth policy --help)
+cauthy-auth theme [options]
 
 Reads the application's Stackmyth theme and gives it to Cauthy's hosted pages.
 
@@ -247,6 +445,8 @@ function fail(message) {
   process.exit(1);
 }
 async function main(argv) {
+  if (argv[0] === "policy") return policy(argv.slice(1));
+  if (argv[0] === "init") return init(argv.slice(1));
   if (argv[0] !== "theme" || argv.includes("--help") || argv.includes("-h")) {
     process.stdout.write(HELP);
     process.exit(argv[0] === "theme" || argv.length === 0 || argv.includes("--help") || argv.includes("-h") ? 0 : 1);
@@ -298,4 +498,4 @@ ${HELP}`);
     process.stdout.write("Not sent. Add --push to give it to Cauthy.\n");
   }
 }
-main(process.argv.slice(2)).catch((err) => fail(err instanceof Error ? err.message.replace(/^@cauthy\/auth: /, "") : String(err)));
+main(process.argv.slice(2)).catch((err) => fail(err instanceof Error ? err.message.replace(/^cauthy-auth: /, "") : String(err)));

package/dist/fastify.d.mts

@@ -1,6 +1,7 @@
 import { FastifyReply, FastifyPluginAsync } from 'fastify';
-import { C as Cauthy } from './cauthy-DsUNqjg6.mjs';
-import { S as Session } from './types-BwCjBn-K.mjs';
+import { C as Cauthy } from './cauthy-mNADGlNl.mjs';
+import { S as Session } from './system-BWLddIt2.mjs';
+import 'jose';
 
 declare module 'fastify' {
     interface FastifyRequest {

package/dist/fastify.d.ts

@@ -1,6 +1,7 @@
 import { FastifyReply, FastifyPluginAsync } from 'fastify';
-import { C as Cauthy } from './cauthy-By2cryXN.js';
-import { S as Session } from './types-BwCjBn-K.js';
+import { C as Cauthy } from './cauthy-C5_lopMQ.js';
+import { S as Session } from './system-BWLddIt2.js';
+import 'jose';
 
 declare module 'fastify' {
     interface FastifyRequest {

package/dist/index.d.mts

@@ -1,3 +1,49 @@
-export { C as Cauthy, R as Resolved, c as createCauthy } from './cauthy-DsUNqjg6.mjs';
-export { C as CauthyConfigError, a as CauthyOptions, J as JsonValue, P as PublicSession, S as Session, b as SessionOrganization, c as SessionStatus, d as SessionUser } from './types-BwCjBn-K.mjs';
+export { C as Cauthy, a as CauthyEvent, b as CauthyWebhookError, R as Resolved, V as VerifyWebhookOptions, c as createCauthy, v as verifyWebhook } from './cauthy-mNADGlNl.mjs';
+export { C as CauthyApiError, a as CauthyConfigError, b as CauthyOptions, c as CauthySystem, J as JsonValue, N as NewMember, O as Organization, d as OrganizationMember, P as PublicSession, S as Session, e as SessionOrganization, f as SessionStatus, g as SessionUser, h as SystemKey, i as SystemOptions, j as createSystem } from './system-BWLddIt2.mjs';
 export { CauthyTheme, ImportedTheme, PushThemeOptions, StackmythThemeOptions, pushTheme, themeFromStackmyth } from './theme.mjs';
+export { P as Permitted, a as PolicyPermission, b as PolicyRole, c as PushPolicyOptions, d as can, p as pushPolicy } from './permissions-B-a3eN0h.mjs';
+import 'jose';
+
+interface ConnectOptions {
+    /** The system's name, as its organizations are filed under: lowercase, digits, - or _. */
+    system: string;
+    /** The application's public address: `https://app.example.com`, or `http://localhost:3000` while developing. */
+    appUrl: string;
+    /** Shown to people on Cauthy's pages. Default: the system's name. */
+    name?: string;
+    /** Where the application serves the return from a sign-in. Default: `/api/auth/callback`. */
+    callbackPath?: string;
+    /** An https address of the application that receives Cauthy's events. */
+    eventsUrl?: string;
+    /** The events to receive. Default: all of them. */
+    events?: string[];
+    /** Where the application publishes its keys, to prove itself without a secret. */
+    jwksUri?: string;
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The workspace's slug. Default: `CAUTHY_TENANT`. */
+    tenant?: string;
+    /** A personal access token with `systems:connect`. Default: `CAUTHY_TOKEN`. */
+    token?: string;
+    fetch?: typeof fetch;
+}
+interface Connected {
+    system: string;
+    clientId: string;
+    /** Shown this once: Cauthy keeps only its hash. */
+    clientSecret: string;
+    redirectUris: string[];
+    webhook: {
+        id: string;
+        url: string;
+        events: string[];
+    } | null;
+    /**
+     * Everything the application sets: what Cauthy answered, plus CAUTHY_SECRET,
+     * the key of the session cookie, generated here and known to nobody else.
+     */
+    env: Record<string, string>;
+}
+declare function connectSystem(o: ConnectOptions): Promise<Connected>;
+
+export { type ConnectOptions, type Connected, connectSystem };

package/dist/index.d.ts

@@ -1,3 +1,49 @@
-export { C as Cauthy, R as Resolved, c as createCauthy } from './cauthy-By2cryXN.js';
-export { C as CauthyConfigError, a as CauthyOptions, J as JsonValue, P as PublicSession, S as Session, b as SessionOrganization, c as SessionStatus, d as SessionUser } from './types-BwCjBn-K.js';
+export { C as Cauthy, a as CauthyEvent, b as CauthyWebhookError, R as Resolved, V as VerifyWebhookOptions, c as createCauthy, v as verifyWebhook } from './cauthy-C5_lopMQ.js';
+export { C as CauthyApiError, a as CauthyConfigError, b as CauthyOptions, c as CauthySystem, J as JsonValue, N as NewMember, O as Organization, d as OrganizationMember, P as PublicSession, S as Session, e as SessionOrganization, f as SessionStatus, g as SessionUser, h as SystemKey, i as SystemOptions, j as createSystem } from './system-BWLddIt2.js';
 export { CauthyTheme, ImportedTheme, PushThemeOptions, StackmythThemeOptions, pushTheme, themeFromStackmyth } from './theme.js';
+export { P as Permitted, a as PolicyPermission, b as PolicyRole, c as PushPolicyOptions, d as can, p as pushPolicy } from './permissions-B-a3eN0h.js';
+import 'jose';
+
+interface ConnectOptions {
+    /** The system's name, as its organizations are filed under: lowercase, digits, - or _. */
+    system: string;
+    /** The application's public address: `https://app.example.com`, or `http://localhost:3000` while developing. */
+    appUrl: string;
+    /** Shown to people on Cauthy's pages. Default: the system's name. */
+    name?: string;
+    /** Where the application serves the return from a sign-in. Default: `/api/auth/callback`. */
+    callbackPath?: string;
+    /** An https address of the application that receives Cauthy's events. */
+    eventsUrl?: string;
+    /** The events to receive. Default: all of them. */
+    events?: string[];
+    /** Where the application publishes its keys, to prove itself without a secret. */
+    jwksUri?: string;
+    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    issuer?: string;
+    /** The workspace's slug. Default: `CAUTHY_TENANT`. */
+    tenant?: string;
+    /** A personal access token with `systems:connect`. Default: `CAUTHY_TOKEN`. */
+    token?: string;
+    fetch?: typeof fetch;
+}
+interface Connected {
+    system: string;
+    clientId: string;
+    /** Shown this once: Cauthy keeps only its hash. */
+    clientSecret: string;
+    redirectUris: string[];
+    webhook: {
+        id: string;
+        url: string;
+        events: string[];
+    } | null;
+    /**
+     * Everything the application sets: what Cauthy answered, plus CAUTHY_SECRET,
+     * the key of the session cookie, generated here and known to nobody else.
+     */
+    env: Record<string, string>;
+}
+declare function connectSystem(o: ConnectOptions): Promise<Connected>;
+
+export { type ConnectOptions, type Connected, connectSystem };