@~lyre/auth 0.0.8 → 0.1.1

package/README.md

@@ -53,6 +53,43 @@ export const handle = createAuthHandle({
 `@sveltejs/kit` is an **optional peer dependency** — only required if you import
 the `/sveltekit` entry.
 
+### `@~lyre/auth/nest` — Nest / Fastify adapter
+
+For services on Nest + Fastify. Adds **no dependencies** — nothing here imports
+`@nestjs/*` or `fastify`; you supply the guard class and DI wiring, the SDK
+supplies the Accounts logic. Works from a plain Fastify app too: any request
+whose `headers` is a plain object satisfies the input type.
+
+```ts
+import { createServiceKeyResolver, createUserSessionResolver, hasScopes }
+  from '@~lyre/auth/nest';
+
+const keys = createServiceKeyResolver({ config: { baseUrl: ACCOUNTS_BASE_URL } });
+const sessions = createUserSessionResolver({ config: { baseUrl: ACCOUNTS_BASE_URL } });
+
+// In a Nest guard (req is the Fastify request):
+const key = await keys.resolve(req);
+if (key.status === 'invalid') throw new UnauthorizedException();  // present but bad
+if (key.status === 'ok') {
+  if (!hasScopes(key.context, ['my-app:things:read'])) throw new ForbiddenException();
+  // key.context.accessibleApps tells you which apps this key may act on
+}
+
+// A user session bearer resolves to who + which app, from the token alone:
+const user = await sessions.resolve(req);
+// → { userId, sessionId, appId, tenantId, email, name } | null
+```
+
+Semantics match `createServiceKeyHandle`: **absent key → `absent`** (fall through to
+other auth), **present-but-invalid → `invalid`** (reject rather than silently
+continue). Introspection is cached by `sha256` of the credential — negative
+results too, so a bad key can't hammer Accounts. Neither resolver throws: a
+transport failure reads as "not authenticated", so a flaky Accounts cannot 500
+the consuming service.
+
+`resolve()` needs `GET /api/auth/me` to return `session.appId` (Accounts ≥ the
+release that added it); older deployments yield `appId: null`.
+
 ## Publishing
 
 See [PUBLISHING.md](PUBLISHING.md). Published to npm via GitHub Actions Trusted

package/dist/{chunk-2FSPKJAC.js → chunk-TQNQLX3C.js}

@@ -278,6 +278,41 @@ async function introspectServiceKey(input) {
     return null;
   }
 }
+async function logoutFromAccounts(input) {
+  const base = normalizeOptionalString(input.config.baseUrl);
+  if (!base || !input.accessToken) return { success: false };
+  const fetchImpl = input.fetchImpl ?? fetch;
+  try {
+    const res = await fetchImpl(new URL("/api/auth/logout", base), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${input.accessToken}`,
+        accept: "application/json"
+      },
+      body: JSON.stringify({ all: input.all ?? false })
+    });
+    if (!res.ok) return { success: false };
+    return await res.json();
+  } catch {
+    return { success: false };
+  }
+}
+function verifyWebhookSignature(rawBody, signature, secret) {
+  if (!signature || !secret) return false;
+  const provided = (signature.startsWith("sha256=") ? signature.slice(7) : signature).toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(provided)) return false;
+  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  const a = Buffer.from(provided, "hex");
+  const b = Buffer.from(expected, "hex");
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+function normalizeAccountsWebhook(payload) {
+  const body = payload && typeof payload === "object" ? payload : {};
+  const type = String(body.event ?? body.type ?? "unknown");
+  return { ...body, type, data: body.data };
+}
 function scopeSatisfied(granted, required) {
   if (!granted || granted.length === 0) return false;
   return granted.includes(required);
@@ -296,5 +331,8 @@ export {
   clearPlatformSessionCookie,
   serviceKeyFromRequest,
   introspectServiceKey,
+  logoutFromAccounts,
+  verifyWebhookSignature,
+  normalizeAccountsWebhook,
   scopeSatisfied
 };

package/dist/index.d.ts

@@ -162,6 +162,30 @@ declare function introspectServiceKey(input: {
     key: string;
     fetchImpl?: typeof fetch;
 }): Promise<ServiceKeyContext | null>;
+declare function logoutFromAccounts(input: {
+    config: Pick<AccountsClientConfig, 'baseUrl'>;
+    accessToken: string;
+    all?: boolean;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    success: boolean;
+    revokedCount?: number;
+}>;
+declare function verifyWebhookSignature(rawBody: string, signature: string | null | undefined, secret: string): boolean;
+type AccountsWebhookEvent = {
+    type: string;
+    data?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Normalize an Accounts webhook body into a stable `AccountsWebhookEvent`.
+ *
+ * The Accounts webhook worker sends `{ event, timestamp, data }` (the event NAME under `event`,
+ * the payload under `data`). Older/other senders may put the name under `type`. This collapses both
+ * so a consumer always reads `event.type` and `event.data`, and keeps the raw fields alongside.
+ * Framework-agnostic so both the SvelteKit handle and the Nest helper share one shape.
+ */
+declare function normalizeAccountsWebhook(payload: unknown): AccountsWebhookEvent;
 declare function scopeSatisfied(granted: string[] | undefined, required: string): boolean;
 
-export { type AccountsClientConfig, type AccountsIdentity, type AccountsTokenResponse, type AuthenticatedPrincipal, type AuthorizationState, type CookieOptions, type LocalUser, type PermissionSet, type PlatformSession, type ServiceKeyApp, type ServiceKeyContext, type SyncAccountsUser, type SyncAccountsUserResult, type TenantAccessContext, type TenantContext, type TenantMembership, beginAccountsLoginRedirect, clearPlatformSessionCookie, createAccountsClientConfig, createPlatformAuth, exchangeAuthorizationCode, handleAccountsCallback, identityPassthroughSync, introspectServiceKey, readPlatformSessionCookie, resolveActiveTenant, scopeSatisfied, serviceKeyFromRequest, syncAccountsUser };
+export { type AccountsClientConfig, type AccountsIdentity, type AccountsTokenResponse, type AccountsWebhookEvent, type AuthenticatedPrincipal, type AuthorizationState, type CookieOptions, type LocalUser, type PermissionSet, type PlatformSession, type ServiceKeyApp, type ServiceKeyContext, type SyncAccountsUser, type SyncAccountsUserResult, type TenantAccessContext, type TenantContext, type TenantMembership, beginAccountsLoginRedirect, clearPlatformSessionCookie, createAccountsClientConfig, createPlatformAuth, exchangeAuthorizationCode, handleAccountsCallback, identityPassthroughSync, introspectServiceKey, logoutFromAccounts, normalizeAccountsWebhook, readPlatformSessionCookie, resolveActiveTenant, scopeSatisfied, serviceKeyFromRequest, syncAccountsUser, verifyWebhookSignature };

package/dist/index.js

@@ -7,12 +7,15 @@ import {
   handleAccountsCallback,
   identityPassthroughSync,
   introspectServiceKey,
+  logoutFromAccounts,
+  normalizeAccountsWebhook,
   readPlatformSessionCookie,
   resolveActiveTenant,
   scopeSatisfied,
   serviceKeyFromRequest,
-  syncAccountsUser
-} from "./chunk-2FSPKJAC.js";
+  syncAccountsUser,
+  verifyWebhookSignature
+} from "./chunk-TQNQLX3C.js";
 export {
   beginAccountsLoginRedirect,
   clearPlatformSessionCookie,
@@ -22,9 +25,12 @@ export {
   handleAccountsCallback,
   identityPassthroughSync,
   introspectServiceKey,
+  logoutFromAccounts,
+  normalizeAccountsWebhook,
   readPlatformSessionCookie,
   resolveActiveTenant,
   scopeSatisfied,
   serviceKeyFromRequest,
-  syncAccountsUser
+  syncAccountsUser,
+  verifyWebhookSignature
 };

package/dist/nest.d.ts

@@ -0,0 +1,85 @@
+import { AccountsWebhookEvent, ServiceKeyContext, AccountsClientConfig } from './index.js';
+export { normalizeAccountsWebhook } from './index.js';
+
+/**
+ * The minimum a request must expose. Fastify's `request` satisfies this as-is
+ * (`headers` is a plain object), as does Node's IncomingMessage.
+ */
+type HeaderCarrier = {
+    headers: Record<string, string | string[] | undefined>;
+};
+/**
+ * Adapt a header-bearing request to the web `Request` that the core helpers expect.
+ * Only headers are needed — `serviceKeyFromRequest` reads `x-api-key` / `authorization`.
+ */
+declare function toWebRequest(carrier: HeaderCarrier): Request;
+/** Extract an `sk_` service key from a Fastify/Node request, or null when absent. */
+declare function serviceKeyFromHeaders(carrier: HeaderCarrier): string | null;
+type ServiceKeyResolverOptions = {
+    config: Pick<AccountsClientConfig, 'baseUrl'>;
+    fetchImpl?: typeof fetch;
+    /** Introspection cache TTL in ms. Default 60_000; 0 disables caching. */
+    cacheTtlMs?: number;
+};
+type ServiceKeyResolution = {
+    status: 'absent';
+} | {
+    status: 'invalid';
+} | {
+    status: 'ok';
+    context: ServiceKeyContext;
+};
+declare function createServiceKeyResolver(opts: ServiceKeyResolverOptions): {
+    resolve: (carrier: HeaderCarrier) => Promise<ServiceKeyResolution>;
+    invalidate: (key: string) => void;
+};
+type UserSessionContext = {
+    userId: string;
+    email?: string;
+    name?: string;
+    sessionId: string;
+    /** The app the session was issued for. Null for sessions created outside an app context. */
+    appId: string | null;
+    tenantId: string | null;
+    expiresAt?: string;
+};
+type UserSessionResolverOptions = {
+    config: Pick<AccountsClientConfig, 'baseUrl'>;
+    fetchImpl?: typeof fetch;
+    /** Cache TTL in ms. Default 60_000; 0 disables caching. */
+    cacheTtlMs?: number;
+};
+/** A session bearer is any Authorization: Bearer token that is NOT an `sk_` service key. */
+declare function sessionTokenFromHeaders(carrier: HeaderCarrier): string | null;
+declare function createUserSessionResolver(opts: UserSessionResolverOptions): {
+    resolve: (carrier: HeaderCarrier) => Promise<UserSessionContext | null>;
+    invalidate: (token: string) => void;
+};
+/**
+ * Whether a resolved key grants every required scope. Uses the core's `scopeSatisfied`
+ * (flat exact match, no wildcards) so behaviour matches Accounts' own enforcement.
+ */
+declare function hasScopes(ctx: ServiceKeyContext, required: readonly string[]): boolean;
+/** Whether a resolved key may act on an app, matched by Accounts app id OR slug. */
+declare function canAccessApp(ctx: ServiceKeyContext, appIdOrSlug: string): boolean;
+type AccountsWebhookResult = {
+    ok: true;
+    event: AccountsWebhookEvent;
+} | {
+    ok: false;
+    reason: 'bad_signature' | 'bad_json';
+};
+/** Header the Accounts webhook worker sends (HMAC-SHA256 hex of the raw body). */
+declare const ACCOUNTS_WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
+/**
+ * Verify an Accounts webhook and parse it into a normalized `{ type, data, ... }` event.
+ *
+ * Pass the RAW request body (a Nest/Fastify controller must read the raw body, not a re-serialized
+ * object — the signature is over the exact bytes), the signature header value
+ * (`request.headers['x-webhook-signature']`), and the shared secret. Returns `{ok:false}` on a bad
+ * signature or unparseable JSON so the controller can 401/400; `{ok:true, event}` otherwise. The
+ * controller then reacts to `event.type` / `event.data` and returns 200 (so Accounts doesn't retry).
+ */
+declare function verifyAndParseAccountsWebhook(rawBody: string, signatureHeaderValue: string | string[] | undefined, secret: string): AccountsWebhookResult;
+
+export { ACCOUNTS_WEBHOOK_SIGNATURE_HEADER, AccountsClientConfig, AccountsWebhookEvent, type AccountsWebhookResult, type HeaderCarrier, ServiceKeyContext, type ServiceKeyResolution, type ServiceKeyResolverOptions, type UserSessionContext, type UserSessionResolverOptions, canAccessApp, createServiceKeyResolver, createUserSessionResolver, hasScopes, serviceKeyFromHeaders, sessionTokenFromHeaders, toWebRequest, verifyAndParseAccountsWebhook };

package/dist/nest.js

@@ -0,0 +1,134 @@
+import {
+  introspectServiceKey,
+  normalizeAccountsWebhook,
+  scopeSatisfied,
+  serviceKeyFromRequest,
+  verifyWebhookSignature
+} from "./chunk-TQNQLX3C.js";
+
+// src/nest.ts
+import { createHash } from "crypto";
+function headerValue(carrier, name) {
+  const v = carrier.headers[name] ?? carrier.headers[name.toLowerCase()];
+  return Array.isArray(v) ? v[0] : v;
+}
+function toWebRequest(carrier) {
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(carrier.headers)) {
+    if (v === void 0) continue;
+    if (Array.isArray(v)) {
+      for (const item of v) headers.append(k, item);
+    } else {
+      headers.set(k, v);
+    }
+  }
+  return new Request("http://localhost/", { headers });
+}
+function serviceKeyFromHeaders(carrier) {
+  return serviceKeyFromRequest(toWebRequest(carrier));
+}
+function createServiceKeyResolver(opts) {
+  const ttl = opts.cacheTtlMs ?? 6e4;
+  const cache = /* @__PURE__ */ new Map();
+  async function resolve(carrier) {
+    const key = serviceKeyFromHeaders(carrier);
+    if (!key) return { status: "absent" };
+    const hash = createHash("sha256").update(key).digest("hex");
+    const now = Date.now();
+    let ctx;
+    const cached = ttl > 0 ? cache.get(hash) : void 0;
+    if (cached && cached.expires > now) {
+      ctx = cached.value;
+    } else {
+      ctx = await introspectServiceKey({ config: opts.config, key, fetchImpl: opts.fetchImpl });
+      if (ttl > 0) cache.set(hash, { value: ctx, expires: now + ttl });
+    }
+    return ctx ? { status: "ok", context: ctx } : { status: "invalid" };
+  }
+  function invalidate(key) {
+    cache.delete(createHash("sha256").update(key).digest("hex"));
+  }
+  return { resolve, invalidate };
+}
+function sessionTokenFromHeaders(carrier) {
+  const auth = headerValue(carrier, "authorization");
+  if (!auth || !auth.startsWith("Bearer ")) return null;
+  const token = auth.slice(7).trim();
+  if (!token || token.startsWith("sk_")) return null;
+  return token;
+}
+function createUserSessionResolver(opts) {
+  const ttl = opts.cacheTtlMs ?? 6e4;
+  const cache = /* @__PURE__ */ new Map();
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  async function introspect(token) {
+    const base = opts.config.baseUrl?.replace(/\/$/, "");
+    if (!base || !token) return null;
+    try {
+      const res = await fetchImpl(new URL("/api/auth/me", base), {
+        headers: { authorization: `Bearer ${token}`, accept: "application/json" }
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      const userId = data.user?.id;
+      const sessionId = data.session?.id;
+      if (!userId || !sessionId) return null;
+      return {
+        userId,
+        email: data.user?.emailAddress ?? data.user?.email,
+        name: data.user?.name,
+        sessionId,
+        appId: data.session?.appId ?? null,
+        tenantId: data.session?.tenantId ?? null,
+        expiresAt: data.session?.expiresAt
+      };
+    } catch {
+      return null;
+    }
+  }
+  async function resolve(carrier) {
+    const token = sessionTokenFromHeaders(carrier);
+    if (!token) return null;
+    const hash = createHash("sha256").update(token).digest("hex");
+    const now = Date.now();
+    const cached = ttl > 0 ? cache.get(hash) : void 0;
+    if (cached && cached.expires > now) return cached.value;
+    const ctx = await introspect(token);
+    if (ttl > 0) cache.set(hash, { value: ctx, expires: now + ttl });
+    return ctx;
+  }
+  function invalidate(token) {
+    cache.delete(createHash("sha256").update(token).digest("hex"));
+  }
+  return { resolve, invalidate };
+}
+function hasScopes(ctx, required) {
+  return required.every((scope) => scopeSatisfied(ctx.scopes, scope));
+}
+function canAccessApp(ctx, appIdOrSlug) {
+  return ctx.accessibleApps.some((a) => a.id === appIdOrSlug || a.slug === appIdOrSlug);
+}
+var ACCOUNTS_WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
+function verifyAndParseAccountsWebhook(rawBody, signatureHeaderValue, secret) {
+  const signature = Array.isArray(signatureHeaderValue) ? signatureHeaderValue[0] : signatureHeaderValue;
+  if (!verifyWebhookSignature(rawBody, signature ?? null, secret)) {
+    return { ok: false, reason: "bad_signature" };
+  }
+  try {
+    return { ok: true, event: normalizeAccountsWebhook(JSON.parse(rawBody)) };
+  } catch {
+    return { ok: false, reason: "bad_json" };
+  }
+}
+export {
+  ACCOUNTS_WEBHOOK_SIGNATURE_HEADER,
+  canAccessApp,
+  createServiceKeyResolver,
+  createUserSessionResolver,
+  hasScopes,
+  normalizeAccountsWebhook,
+  serviceKeyFromHeaders,
+  sessionTokenFromHeaders,
+  toWebRequest,
+  verifyAndParseAccountsWebhook
+};

package/dist/sveltekit.d.ts

@@ -1,5 +1,5 @@
 import { RequestEvent, Handle } from '@sveltejs/kit';
-import { PlatformSession, AccountsClientConfig, ServiceKeyContext, SyncAccountsUser, CookieOptions } from './index.js';
+import { AccountsWebhookEvent, PlatformSession, AccountsClientConfig, ServiceKeyContext, SyncAccountsUser, CookieOptions } from './index.js';
 export { clearPlatformSessionCookie } from './index.js';
 
 type SvelteKitAuthOptions = {
@@ -51,5 +51,18 @@ type ServiceKeyLocals = {
     serviceKey?: ServiceKeyContext | null;
 };
 declare function createServiceKeyHandle(opts: ServiceKeyHandleOptions): Handle;
+type AccountsWebhookOptions = {
+    secret: string;
+    /** Route to receive webhooks on. Default '/api/auth/accounts/webhook'. */
+    path?: string;
+    /**
+     * Header carrying the signature. Default 'x-webhook-signature' — the header the Accounts
+     * webhook worker actually sends (HMAC-SHA256 hex of the raw body).
+     */
+    signatureHeader?: string;
+    /** React to a verified event. Throwing yields a 500 (Accounts may retry). */
+    onEvent: (event: AccountsWebhookEvent, raw: string, request: RequestEvent) => void | Promise<void>;
+};
+declare function createAccountsWebhookHandle(opts: AccountsWebhookOptions): Handle;
 
-export { type PlatformLocals, type ServiceKeyHandleOptions, type ServiceKeyLocals, type SvelteKitAuthOptions, createAuthHandle, createServiceKeyHandle };
+export { type AccountsWebhookOptions, type PlatformLocals, type ServiceKeyHandleOptions, type ServiceKeyLocals, type SvelteKitAuthOptions, createAccountsWebhookHandle, createAuthHandle, createServiceKeyHandle };

package/dist/sveltekit.js

@@ -4,9 +4,12 @@ import {
   handleAccountsCallback,
   identityPassthroughSync,
   introspectServiceKey,
+  logoutFromAccounts,
+  normalizeAccountsWebhook,
   readPlatformSessionCookie,
-  serviceKeyFromRequest
-} from "./chunk-2FSPKJAC.js";
+  serviceKeyFromRequest,
+  verifyWebhookSignature
+} from "./chunk-TQNQLX3C.js";
 
 // src/sveltekit.ts
 import { createHash } from "crypto";
@@ -55,6 +58,10 @@ function createAuthHandle(opts) {
       ]);
     }
     if (path === logoutPath) {
+      if (session.accessToken) {
+        const all = event.url.searchParams.get("all") === "1" || event.url.searchParams.get("all") === "true";
+        await logoutFromAccounts({ config: opts.config, accessToken: session.accessToken, all });
+      }
       return redirectWithCookies(postLogoutPath, [
         clearPlatformSessionCookie(cookieOptions),
         `${STATE_COOKIE}=; ${cookieOptions?.sameSite === "none" ? "Path=/; HttpOnly; SameSite=None; Secure" : "Path=/; HttpOnly; SameSite=Lax"}; Max-Age=0`
@@ -102,8 +109,35 @@ function createServiceKeyHandle(opts) {
     });
   };
 }
+function jsonResponse(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+function createAccountsWebhookHandle(opts) {
+  const path = opts.path ?? "/api/auth/accounts/webhook";
+  const sigHeader = opts.signatureHeader ?? "x-webhook-signature";
+  return async ({ event, resolve }) => {
+    if (event.url.pathname !== path || event.request.method !== "POST") return resolve(event);
+    const raw = await event.request.text();
+    if (!verifyWebhookSignature(raw, event.request.headers.get(sigHeader), opts.secret)) {
+      return jsonResponse(401, { ok: false, error: "Invalid webhook signature." });
+    }
+    let parsed;
+    try {
+      parsed = normalizeAccountsWebhook(JSON.parse(raw));
+    } catch {
+      return jsonResponse(400, { ok: false, error: "Invalid JSON body." });
+    }
+    try {
+      await opts.onEvent(parsed, raw, event);
+    } catch {
+      return jsonResponse(500, { ok: false, error: "Webhook handler failed." });
+    }
+    return jsonResponse(200, { ok: true });
+  };
+}
 export {
   clearPlatformSessionCookie,
+  createAccountsWebhookHandle,
   createAuthHandle,
   createServiceKeyHandle
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@~lyre/auth",
-  "version": "0.0.8",
+  "version": "0.1.1",
   "description": "Shared Axis Accounts auth SDK — framework-agnostic session/identity core (HMAC-signed cookies, accounts login/callback/logout) plus an optional turnkey SvelteKit adapter.",
   "type": "module",
   "sideEffects": false,
@@ -33,7 +33,12 @@
     "./sveltekit": {
       "types": "./dist/sveltekit.d.ts",
       "import": "./dist/sveltekit.js"
-    }
+    },
+    "./nest": {
+      "types": "./dist/nest.d.ts",
+      "import": "./dist/nest.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -41,7 +46,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/sveltekit.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/sveltekit.ts src/nest.ts --format esm --dts --clean",
     "check": "tsc --noEmit"
   },
   "peerDependencies": {