cauthy-auth 0.2.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-BrIMaoj1.d.mts → cauthy-C5_lopMQ.d.ts}

@@ -1,5 +1,5 @@
+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';
-import { J as JsonValue, S as Session, c as SessionStatus, b as SessionOrganization, P as PublicSession, a as CauthyOptions } from './types-CYmUVWzY.mjs';
 
 /** Something that happened in Cauthy, as a subscriber is told. Moments are UTC. */
 interface CauthyEvent {
@@ -86,6 +86,12 @@ interface Cauthy {
      * 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. */

package/dist/{cauthy-CCZc9w8r.d.ts → cauthy-mNADGlNl.d.mts}

@@ -1,5 +1,5 @@
+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';
-import { J as JsonValue, S as Session, c as SessionStatus, b as SessionOrganization, P as PublicSession, a as CauthyOptions } from './types-CYmUVWzY.js';
 
 /** Something that happened in Cauthy, as a subscriber is told. Moments are UTC. */
 interface CauthyEvent {
@@ -86,6 +86,12 @@ interface Cauthy {
      * 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. */

package/dist/cli.js

@@ -4,6 +4,53 @@
 // 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;
@@ -246,6 +293,77 @@ async function pushTheme(o) {
 }
 
 // src/cli.ts
+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:
@@ -303,7 +421,9 @@ ${POLICY_HELP}`);
     process.stdout.write("Not sent. Add --push to give it to Cauthy.\n");
   }
 }
-var HELP = `cauthy-auth theme [options]
+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.
 
@@ -326,6 +446,7 @@ function fail(message) {
 }
 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);
@@ -377,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,6 @@
 import { FastifyReply, FastifyPluginAsync } from 'fastify';
-import { C as Cauthy } from './cauthy-BrIMaoj1.mjs';
-import { S as Session } from './types-CYmUVWzY.mjs';
+import { C as Cauthy } from './cauthy-mNADGlNl.mjs';
+import { S as Session } from './system-BWLddIt2.mjs';
 import 'jose';
 
 declare module 'fastify' {

package/dist/fastify.d.ts

@@ -1,6 +1,6 @@
 import { FastifyReply, FastifyPluginAsync } from 'fastify';
-import { C as Cauthy } from './cauthy-CCZc9w8r.js';
-import { S as Session } from './types-CYmUVWzY.js';
+import { C as Cauthy } from './cauthy-C5_lopMQ.js';
+import { S as Session } from './system-BWLddIt2.js';
 import 'jose';
 
 declare module 'fastify' {

package/dist/index.d.mts

@@ -1,5 +1,49 @@
-export { C as Cauthy, a as CauthyEvent, b as CauthyWebhookError, R as Resolved, V as VerifyWebhookOptions, c as createCauthy, v as verifyWebhook } from './cauthy-BrIMaoj1.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-CYmUVWzY.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,5 +1,49 @@
-export { C as Cauthy, a as CauthyEvent, b as CauthyWebhookError, R as Resolved, V as VerifyWebhookOptions, c as createCauthy, v as verifyWebhook } from './cauthy-CCZc9w8r.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-CYmUVWzY.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 };