cauthy-auth 0.1.0 → 0.2.0

package/dist/{cauthy-DsUNqjg6.d.mts → cauthy-BrIMaoj1.d.mts}

@@ -1,4 +1,44 @@
-import { S as Session, c as SessionStatus, b as SessionOrganization, P as PublicSession, a as CauthyOptions } from './types-BwCjBn-K.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.mjs';
+
+/** 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 {
@@ -40,6 +80,12 @@ interface Cauthy {
     }>;
     /** 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>;
     /** 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. */
@@ -53,4 +99,4 @@ interface Cauthy {
 }
 declare function createCauthy(given?: CauthyOptions): Cauthy;
 
-export { type Cauthy as C, type Resolved as R, createCauthy as c };
+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-By2cryXN.d.ts → cauthy-CCZc9w8r.d.ts}

@@ -1,4 +1,44 @@
-import { S as Session, c as SessionStatus, b as SessionOrganization, P as PublicSession, a as CauthyOptions } from './types-BwCjBn-K.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.js';
+
+/** 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 {
@@ -40,6 +80,12 @@ interface Cauthy {
     }>;
     /** 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>;
     /** 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. */
@@ -53,4 +99,4 @@ interface Cauthy {
 }
 declare function createCauthy(given?: CauthyOptions): Cauthy;
 
-export { type Cauthy as C, type Resolved as R, createCauthy as c };
+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,27 @@
 // src/cli.ts
 var import_node_fs = require("fs");
 
+// 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,6 +246,63 @@ async function pushTheme(o) {
 }
 
 // src/cli.ts
+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 theme [options]
 
 Reads the application's Stackmyth theme and gives it to Cauthy's hosted pages.
@@ -247,6 +325,7 @@ function fail(message) {
   process.exit(1);
 }
 async function main(argv) {
+  if (argv[0] === "policy") return policy(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);

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-BrIMaoj1.mjs';
+import { S as Session } from './types-CYmUVWzY.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-CCZc9w8r.js';
+import { S as Session } from './types-CYmUVWzY.js';
+import 'jose';
 
 declare module 'fastify' {
     interface FastifyRequest {

package/dist/index.d.mts

@@ -1,3 +1,5 @@
-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-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 { 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';

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-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-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 { 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';

package/dist/index.js

@@ -21,9 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   CauthyConfigError: () => CauthyConfigError,
+  CauthyWebhookError: () => CauthyWebhookError,
+  can: () => can,
   createCauthy: () => createCauthy,
+  pushPolicy: () => pushPolicy,
   pushTheme: () => pushTheme,
-  themeFromStackmyth: () => themeFromStackmyth
+  themeFromStackmyth: () => themeFromStackmyth,
+  verifyWebhook: () => verifyWebhook
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -83,6 +87,77 @@ async function unseal(sealed, key) {
   }
 }
 
+// src/webhook.ts
+var import_jose2 = require("jose");
+var CauthyWebhookError = class extends Error {
+  constructor(reason) {
+    super(`cauthy-auth: webhook refused: ${reason}`);
+    this.reason = reason;
+    this.name = "CauthyWebhookError";
+  }
+  reason;
+};
+var keys = /* @__PURE__ */ new Map();
+function keysOf(issuer) {
+  let set = keys.get(issuer);
+  if (set === void 0) {
+    set = (0, import_jose2.createRemoteJWKSet)(new URL(`${issuer}/.well-known/jwks.json`), { cooldownDuration: 3e4 });
+    keys.set(issuer, set);
+  }
+  return set;
+}
+var hex = (s) => typeof s === "string" && s !== "" ? s : void 0;
+async function verifyWebhook(request, options = {}) {
+  const env2 = typeof process !== "undefined" ? process.env?.CAUTHY_ISSUER : void 0;
+  const issuer = (options.issuer ?? env2 ?? "").replace(/\/+$/, "");
+  if (issuer === "") throw new CauthyWebhookError("issuer (CAUTHY_ISSUER) is not set");
+  const signature = request.headers.get("x-cauthy-signature-jwt");
+  if (!signature) throw new CauthyWebhookError("no signature");
+  const raw = new Uint8Array(await request.arrayBuffer());
+  const audience = options.url ?? request.url.split("?")[0];
+  let claims;
+  try {
+    const verified = await (0, import_jose2.jwtVerify)(signature, options.jwks ?? keysOf(issuer), {
+      algorithms: ["RS256"],
+      issuer,
+      audience,
+      typ: "cauthy-webhook+jwt",
+      requiredClaims: ["exp", "iat", "jti", "body_sha256"],
+      currentDate: options.now,
+      clockTolerance: 30
+    });
+    claims = verified.payload;
+  } catch (err) {
+    throw new CauthyWebhookError(err instanceof Error ? err.message : "bad signature");
+  }
+  const now = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+  if (typeof claims.iat !== "number" || claims.iat > now + 30) throw new CauthyWebhookError("signed in the future");
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", raw));
+  let b64 = "";
+  for (const b of digest) b64 += String.fromCharCode(b);
+  const hash = btoa(b64).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  if (hash !== claims.body_sha256) throw new CauthyWebhookError("the body is not the one that was signed");
+  let body;
+  try {
+    body = JSON.parse(new TextDecoder().decode(raw));
+  } catch {
+    throw new CauthyWebhookError("the body is not JSON");
+  }
+  if (body.id !== claims.jti || body.event !== claims.evt || body.tenant_id !== claims.tid) {
+    throw new CauthyWebhookError("the body and its signature disagree");
+  }
+  const inner = body.data ?? {};
+  return {
+    id: String(body.id),
+    type: String(body.event),
+    tenantId: String(body.tenant_id),
+    createdAt: String(inner.created_at ?? body.created_at ?? ""),
+    ...hex(inner.user_id) ? { userId: inner.user_id } : {},
+    ...hex(inner.actor_id) ? { actorId: inner.actor_id } : {},
+    data: inner.data ?? {}
+  };
+}
+
 // src/types.ts
 var CauthyConfigError = class extends Error {
   constructor(message) {
@@ -265,7 +340,8 @@ function createCauthy(given = {}) {
         kind: String(o.kind ?? ""),
         role: String(o.role ?? ""),
         metadata: o.metadata ?? {},
-        ...o.external_id ? { externalId: String(o.external_id) } : {}
+        ...o.external_id ? { externalId: String(o.external_id) } : {},
+        ...Array.isArray(o.permissions) ? { permissions: o.permissions.map(String), denied: Array.isArray(o.denied) ? o.denied.map(String) : [] } : {}
       })
     );
     if (orgCache.size > 5e3) orgCache.clear();
@@ -391,8 +467,10 @@ function createCauthy(given = {}) {
     const to = value === null ? urls.signIn(back) : `${basePath}/refresh?return_to=${encodeURIComponent(back)}`;
     return { response: redirect(to) };
   }
+  const webhook = (request, o = {}) => verifyWebhook(request, { issuer, url: o.url ?? `${originOf(request)}${new URL(request.url).pathname}`, jwks: o.jwks, now: o.now });
   return {
     handler,
+    webhook,
     getSession,
     status,
     resolve: resolve2,
@@ -623,11 +701,48 @@ async function pushTheme(o) {
     throw new Error(`cauthy-auth: Cauthy refused the theme (${res.status}): ${body?.errors?.[0]?.message ?? res.statusText}`);
   }
 }
+
+// src/permissions.ts
+function matches(entry, resource, action) {
+  const i = entry.lastIndexOf(":");
+  if (i < 0) return false;
+  const r = entry.slice(0, i);
+  const a = entry.slice(i + 1);
+  return (r === "*" || r === resource) && (a === "*" || a === action);
+}
+function can(organization, resource, action) {
+  if (!organization?.permissions) return false;
+  if ((organization.denied ?? []).some((d) => matches(d, resource, action))) return false;
+  return organization.permissions.some((p) => matches(p, resource, action));
+}
+async function pushPolicy(o) {
+  const env2 = (n) => typeof process !== "undefined" ? process.env?.[n] : void 0;
+  const issuer = (o.issuer ?? env2("CAUTHY_ISSUER") ?? "").replace(/\/+$/, "");
+  const system = o.system ?? env2("CAUTHY_SYSTEM") ?? "";
+  const tenant = o.tenant ?? env2("CAUTHY_TENANT") ?? "";
+  const token = o.token ?? env2("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}`);
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CauthyConfigError,
+  CauthyWebhookError,
+  can,
   createCauthy,
+  pushPolicy,
   pushTheme,
-  themeFromStackmyth
+  themeFromStackmyth,
+  verifyWebhook
 });
 //# sourceMappingURL=index.js.map