@adonis-agora/authkit-client 1.0.0-rc.6 → 1.0.0-rc.7

package/build/src/webhook_receiver.js

@@ -0,0 +1,161 @@
+/**
+ * Receives authkit-server's signed event webhook on another server and re-emits each
+ * event on the local `@adonis-agora/diagnostics` bus as `agora:authkit:<type>`, with the
+ * same payload authkit-server emits in-process. Listeners such as authz provisioning
+ * (`onDiagnostic('authkit', 'organization.created', ...)`) then work unchanged when
+ * authkit runs elsewhere.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** In-memory replay store: ids live for their TTL, at most `max` at a time. */
+export function memoryReplayStore(max = 10_000) {
+    const seen = new Map();
+    return {
+        claim(id, ttlMs) {
+            const now = Date.now();
+            const expiresAt = seen.get(id);
+            if (expiresAt !== undefined && expiresAt > now)
+                return false;
+            seen.delete(id);
+            seen.set(id, now + ttlMs);
+            if (seen.size > max) {
+                for (const [key, exp] of seen) {
+                    if (exp <= now || seen.size > max)
+                        seen.delete(key);
+                    else
+                        break;
+                }
+            }
+            return true;
+        },
+    };
+}
+function validSignature(body, header, secret) {
+    if (typeof header !== 'string' || !header.startsWith('sha256='))
+        return false;
+    const expected = Buffer.from(createHmac('sha256', secret).update(body).digest('hex'));
+    const given = Buffer.from(header.slice('sha256='.length));
+    return given.length === expected.length && timingSafeEqual(given, expected);
+}
+const str = (v) => (typeof v === 'string' && v ? v : null);
+/**
+ * Checks one delivery: the `x-authkit-signature` HMAC over the raw body, the shape, the
+ * `ts` window and the `id` (each id is accepted once). Pure apart from the replay store.
+ */
+export async function verifyAuthkitWebhook(input, options) {
+    if (!validSignature(input.body, input.signature, options.secret)) {
+        return { ok: false, reason: 'signature' };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(input.body);
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    const id = str(raw?.id);
+    const type = str(raw?.type);
+    const ts = str(raw?.ts);
+    if (!id || !type || !ts)
+        return { ok: false, reason: 'malformed' };
+    const at = Date.parse(ts);
+    if (Number.isNaN(at))
+        return { ok: false, reason: 'malformed' };
+    const toleranceMs = (options.toleranceSec ?? 300) * 1000;
+    if (Math.abs(Date.now() - at) > toleranceMs)
+        return { ok: false, reason: 'expired' };
+    // Remember the id for as long as its `ts` stays acceptable.
+    if (!(await options.replayStore.claim(id, toleranceMs * 2))) {
+        return { ok: false, reason: 'replay' };
+    }
+    const metadata = raw.metadata && typeof raw.metadata === 'object' && !Array.isArray(raw.metadata)
+        ? raw.metadata
+        : {};
+    return {
+        ok: true,
+        event: {
+            id,
+            type,
+            accountId: str(raw.accountId),
+            actorId: str(raw.actorId),
+            email: str(raw.email),
+            clientId: str(raw.clientId),
+            orgId: str(raw.orgId),
+            ip: str(raw.ip),
+            metadata,
+            ts,
+        },
+    };
+}
+const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit');
+/**
+ * Emits `event` on the diagnostics bus as `agora:authkit:<type>` with authkit-server's
+ * redacted payload (`type`, `accountId`, `actorId`, `clientId`, `orgId`). No-op without
+ * `@adonis-agora/diagnostics`.
+ */
+export function emitAuthkitEvent(event) {
+    try {
+        const emit = globalThis[EMIT_SLOT];
+        emit?.('authkit', event.type, {
+            type: event.type,
+            accountId: event.accountId,
+            actorId: event.actorId,
+            clientId: event.clientId,
+            orgId: event.orgId,
+        });
+    }
+    catch {
+        // best effort
+    }
+}
+/**
+ * The route handler for authkit-server's webhook. Answers `204` for an accepted (or
+ * replayed) delivery, `401` for a bad signature, `400` for a malformed or expired one.
+ * Needs the raw body: keep the route under the JSON body parser (the default) and out of
+ * CSRF (shield's `csrf.exceptRoutes`).
+ */
+export function authkitWebhookHandler(options) {
+    if (!options?.secret)
+        throw new TypeError('authkitWebhookHandler: secret is required');
+    const replayStore = options.replayStore ?? memoryReplayStore();
+    return async (ctx) => {
+        const body = ctx.request.raw();
+        if (typeof body !== 'string' || !body) {
+            return ctx.response.badRequest({ error: 'malformed' });
+        }
+        const verdict = await verifyAuthkitWebhook({ body, signature: ctx.request.header('x-authkit-signature') }, { secret: options.secret, toleranceSec: options.toleranceSec, replayStore });
+        if (!verdict.ok) {
+            if (verdict.reason === 'replay')
+                return ctx.response.noContent();
+            if (verdict.reason === 'signature') {
+                return ctx.response.unauthorized({ error: 'invalid_signature' });
+            }
+            return ctx.response.badRequest({ error: verdict.reason });
+        }
+        try {
+            if (options.onEvent)
+                await options.onEvent(verdict.event);
+        }
+        catch {
+            // A failing listener must not suppress the bus emit: the delivery was valid and its id
+            // is already claimed, so a redelivery would be ignored.
+        }
+        if (options.emit !== false)
+            emitAuthkitEvent(verdict.event);
+        return ctx.response.noContent();
+    };
+}
+/**
+ * Mounts `POST path` (default `/authkit/webhook`) with {@link authkitWebhookHandler}:
+ *
+ * ```ts
+ * // start/routes.ts
+ * registerAuthkitWebhook(router, { secret: env.get('AUTHKIT_WEBHOOK_SECRET') })
+ * ```
+ *
+ * Point authkit-server's `events.webhook` at `https://<this app>/authkit/webhook` with the
+ * same secret, and add the path to shield's `csrf.exceptRoutes`.
+ */
+export function registerAuthkitWebhook(router, options) {
+    const { path = '/authkit/webhook', ...rest } = options;
+    router.post(path, authkitWebhookHandler(rest)).as('authkit.webhook');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "description": "AdonisJS OIDC/OAuth2 relying-party (client) toolkit: session-based authentication against an OpenID Connect identity provider, with JWT/PAT user resolvers and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -77,11 +77,11 @@
     }
   },
   "dependencies": {
-    "@adonis-agora/authkit-core": "1.0.0-rc.2",
+    "@adonis-agora/authkit-core": "1.0.0-rc.3",
     "jose": "6.2.16"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "1.0.0-rc.12",
+    "@adonis-agora/authkit-server": "1.0.0-rc.24",
     "@adonis-agora/resilience": "0.4.3",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",

package/skills/authkit-rp-client/SKILL.md

@@ -206,6 +206,30 @@ validated `{ sid, sub }` (store runs first, then the hook).
 
 Source: `src/define_config.ts` (`BackchannelLogoutInput`), README.
 
+### Pattern 5 — authkit-server on another server
+
+Nothing on this server may need authkit-server in-process. The remote-safe helpers:
+
+```ts
+import {
+  authkitTenantToken, // tenant side: client_credentials token for one resource; endpoint from discovery only
+  authkitTenantVerifier, // control-plane side: (request) => { partition, environment?, capabilities, clientId, expiresAt } | null
+  registerAuthkitWebhook, // signed authkit events → diagnostics bus as agora:authkit:<type>
+  bridgeAuthkitToken, // bearer token (MCP/API) → ctx.authkit, so authkitDashboardAuthorize admits it
+} from '@adonis-agora/authkit-client'
+
+verifyTenant: authkitTenantVerifier({ issuer: env.get('AUTHKIT_ISSUER'), resource: 'urn:agora:flags' })
+registerAuthkitWebhook(router, { secret: env.get('AUTHKIT_WEBHOOK_SECRET') }) // + csrf.exceptRoutes
+```
+
+`registerOidcClient` already announces `POST /auth/logout` as the consoles' sign-out (skipped
+when authkit-server runs in the app), the provider installs org labels (`orgLabels`), and
+`identity.actor` carries the impersonating admin (`act`). Resources are `urn:agora:<product>`;
+never hard-code `/token` or `/oauth/token`.
+
+Source: `src/tenant_verifier.ts`, `src/webhook_receiver.ts`, `src/identity_bridge.ts`,
+`src/org_labels.ts`; docs `topologies.mdx`.
+
 ## Common mistakes
 
 ### HIGH — Session middleware running after `authkit_context_middleware`