authfyio-backend 0.2.1

package/README.md

@@ -0,0 +1,88 @@
+# authfyio-backend
+
+Server-side SDK for verifying Authfyio sessions in Node.js backends. Built for Express, Fastify, Nest, Koa, Hono, bare `http`, or anything that exposes a standard cookie header.
+
+## What it does
+
+- Verifies the short-lived `__session` JWT issued by a Authfyio instance against its JWKS endpoint.
+- Parses `Cookie` headers and extracts the session JWT without you having to touch cookie-parsing middleware.
+- Returns fully-typed session claims: `sub` (user id), `sid` (session id), `env` (environment id), plus any custom claims your instance has attached.
+
+It does **not** perform user creation, password flows, or OAuth redirects — those belong on the instance API and in the browser SDK (`authfyio-react`, `authfyio-nextjs`). This package exists so your backend can trust a request without a round-trip to the auth service on every call.
+
+## Install
+
+```bash
+npm install authfyio-backend
+# or within the monorepo
+npm install -w authfyio-backend
+```
+
+Requires Node 20+.
+
+## Quick start
+
+```ts
+import { AuthfyioBackendClient } from 'authfyio-backend';
+
+const af = new AuthfyioBackendClient({
+  baseUrl: process.env.AF_API_BASE_URL!,       // e.g. https://auth.example.com
+  issuer: process.env.AF_JWT_ISSUER,           // matches the instance `iss`
+  audience: process.env.AF_JWT_AUDIENCE,       // optional
+});
+
+// Express
+app.get('/api/me', async (req, res) => {
+  const session = await af.getSessionFromRequest(req);
+  if (!session) return res.status(401).json({ error: 'unauthenticated' });
+
+  res.json({
+    userId: session.sub,
+    sessionId: session.sid,
+    environment: session.env,
+  });
+});
+```
+
+The client fetches and caches JWKS the first time you verify a token. JWKS rotation is picked up automatically on cache expiry — you do not need to restart your service after a key rotation on the auth side.
+
+## API
+
+### `new AuthfyioBackendClient(options)`
+
+| Option      | Type     | Required | Description                                                                   |
+| ----------- | -------- | -------- | ----------------------------------------------------------------------------- |
+| `baseUrl`   | `string` | yes      | Instance API base URL. JWKS is discovered at `${baseUrl}/.well-known/jwks.json`. |
+| `issuer`    | `string` | no       | Expected `iss` claim. Strongly recommended in production.                      |
+| `audience`  | `string` | no       | Expected `aud` claim, if your instance sets it.                                |
+
+### `client.verifySessionJwt(token)`
+
+Verifies the token against the instance's JWKS and returns the claims. Throws if the token is invalid, expired, or signed by an unknown key.
+
+### `client.getSessionFromRequest(req)`
+
+Pulls the `__session` cookie out of `req.headers.cookie`, then verifies it. Returns `null` when no cookie is present. Throws on an invalid token so your error middleware can decide how to respond.
+
+### Low-level helpers
+
+- `parseCookieHeader(header)` — returns a plain `Record<string, string>`.
+- `getSessionJwtFromCookieHeader(header)` — returns the `__session` JWT or `null`.
+- `verifySessionJwt(token, options)` — standalone verifier if you prefer not to use the class.
+
+## How sessions work (short version)
+
+Authfyio uses a two-cookie design:
+
+- `__client` (httpOnly, long-lived) holds the refresh-capable session reference. It never leaves the browser → auth-API roundtrip.
+- `__session` (readable by JS, ~60s TTL) is a signed JWT your services verify locally. Short lifetime means a revoked session stops working within the skew window without you having to hit the auth API.
+
+This package is the "verify `__session` locally" half. The browser SDK handles the refresh loop.
+
+## Error handling
+
+`jose`-thrown errors bubble up with their original names (`JWSSignatureVerificationFailed`, `JWTExpired`, etc.). Production services should log the error class, not the token, and return a generic 401 to the client.
+
+## License
+
+MIT

package/dist/admin.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Admin SDK — server-to-server calls to the instance API's `/v1/admin/*`
+ * surface. Authenticates with a secret API key minted from the dashboard.
+ *
+ *     const kolay = createAuthfyioClient({
+ *       secretKey: process.env.AUTHFYIO_SECRET_KEY!,  // sk_live_...
+ *     });
+ *     const { users } = await kolay.users.list({ limit: 10 });
+ */
+export type AuthfyioClientOptions = {
+    baseUrl: string;
+    /** Bearer token starting with `sk_live_` or `sk_test_`. */
+    secretKey: string;
+    /** Optional fetch override (for Node < 18 or test mocks). */
+    fetch?: typeof fetch;
+};
+export type AdminUser = {
+    id: string;
+    username: string | null;
+    externalId: string | null;
+    isBanned: boolean;
+    banReason: string | null;
+    publicMetadata: Record<string, unknown>;
+    privateMetadata: Record<string, unknown>;
+    unsafeMetadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    emails: Array<{
+        email: string;
+        isPrimary: boolean;
+        isVerified: boolean;
+    }>;
+};
+export type AdminOrganization = {
+    id: string;
+    name: string;
+    slug: string;
+    createdAt: string;
+};
+export type AdminSession = {
+    id: string;
+    userId: string;
+    status: 'active' | 'ended' | 'expired' | 'revoked';
+    activeOrgId: string | null;
+    createdAt: string;
+    expiresAt: string;
+    endedAt: string | null;
+};
+export type AdminInvitation = {
+    id: string;
+    email: string;
+    role: string;
+    /** Returned once at creation; use to build your own invite-email URL. */
+    token?: string;
+};
+export declare class AuthfyioAdminClient {
+    private readonly baseUrl;
+    private readonly secretKey;
+    private readonly fetchImpl;
+    readonly users: UsersResource;
+    readonly organizations: OrganizationsResource;
+    readonly invitations: InvitationsResource;
+    readonly sessions: SessionsResource;
+    constructor(opts: AuthfyioClientOptions);
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+}
+declare class UsersResource {
+    private readonly client;
+    constructor(client: AuthfyioAdminClient);
+    list(params?: {
+        limit?: number;
+        offset?: number;
+        email?: string;
+    }): Promise<{
+        users: AdminUser[];
+        total: number;
+    }>;
+    get(userId: string): Promise<AdminUser>;
+    update(userId: string, patch: Partial<Pick<AdminUser, 'username' | 'externalId' | 'isBanned' | 'banReason' | 'publicMetadata' | 'privateMetadata'>>): Promise<void>;
+    ban(userId: string, reason?: string): Promise<void>;
+    unban(userId: string): Promise<void>;
+    delete(userId: string): Promise<void>;
+}
+declare class OrganizationsResource {
+    private readonly client;
+    constructor(client: AuthfyioAdminClient);
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        organizations: AdminOrganization[];
+        total: number;
+    }>;
+    create(params: {
+        name: string;
+        slug: string;
+        createdBy?: string;
+    }): Promise<AdminOrganization>;
+    delete(orgId: string): Promise<void>;
+    addMember(orgId: string, params: {
+        userId: string;
+        role?: string;
+    }): Promise<void>;
+    removeMember(orgId: string, userId: string): Promise<void>;
+}
+declare class InvitationsResource {
+    private readonly client;
+    constructor(client: AuthfyioAdminClient);
+    create(params: {
+        email: string;
+        orgId: string;
+        role?: string;
+    }): Promise<AdminInvitation>;
+    revoke(invitationId: string): Promise<void>;
+}
+declare class SessionsResource {
+    private readonly client;
+    constructor(client: AuthfyioAdminClient);
+    list(params?: {
+        userId?: string;
+        limit?: number;
+    }): Promise<{
+        sessions: AdminSession[];
+    }>;
+    revoke(sessionId: string): Promise<void>;
+}
+/** Factory function — */
+export declare function createAuthfyioClient(opts: AuthfyioClientOptions): AuthfyioAdminClient;
+export {};
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"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"}

package/dist/admin.js

@@ -0,0 +1,166 @@
+/**
+ * Admin SDK — server-to-server calls to the instance API's `/v1/admin/*`
+ * surface. Authenticates with a secret API key minted from the dashboard.
+ *
+ *     const kolay = createAuthfyioClient({
+ *       secretKey: process.env.AUTHFYIO_SECRET_KEY!,  // sk_live_...
+ *     });
+ *     const { users } = await kolay.users.list({ limit: 10 });
+ */
+export class AuthfyioAdminClient {
+    baseUrl;
+    secretKey;
+    fetchImpl;
+    users;
+    organizations;
+    invitations;
+    sessions;
+    constructor(opts) {
+        if (!opts.secretKey?.startsWith('sk_')) {
+            throw new Error('AuthfyioAdminClient: secretKey must start with sk_');
+        }
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.secretKey = opts.secretKey;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        this.users = new UsersResource(this);
+        this.organizations = new OrganizationsResource(this);
+        this.invitations = new InvitationsResource(this);
+        this.sessions = new SessionsResource(this);
+    }
+    async request(path, init) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+                authorization: `Bearer ${this.secretKey}`,
+                ...(init?.headers ?? {}),
+            },
+        });
+        const text = await res.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = null;
+        }
+        if (!res.ok) {
+            const err = new Error(body?.message ?? `authfyio_admin_${res.status}`);
+            err.status = res.status;
+            err.body = body;
+            throw err;
+        }
+        return body;
+    }
+}
+class UsersResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list(params) {
+        const qs = new URLSearchParams();
+        if (params?.limit !== undefined)
+            qs.set('limit', String(params.limit));
+        if (params?.offset !== undefined)
+            qs.set('offset', String(params.offset));
+        if (params?.email)
+            qs.set('email', params.email);
+        const body = await this.client.request(`/v1/admin/users${qs.toString() ? '?' + qs : ''}`);
+        return { users: body.users ?? [], total: body.total ?? 0 };
+    }
+    async get(userId) {
+        const body = await this.client.request(`/v1/admin/users/${encodeURIComponent(userId)}`);
+        return body.user;
+    }
+    async update(userId, patch) {
+        await this.client.request(`/v1/admin/users/${encodeURIComponent(userId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(patch),
+        });
+    }
+    async ban(userId, reason) {
+        return this.update(userId, { isBanned: true, banReason: reason ?? null });
+    }
+    async unban(userId) {
+        return this.update(userId, { isBanned: false, banReason: null });
+    }
+    async delete(userId) {
+        await this.client.request(`/v1/admin/users/${encodeURIComponent(userId)}`, { method: 'DELETE' });
+    }
+}
+class OrganizationsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list(params) {
+        const qs = new URLSearchParams();
+        if (params?.limit !== undefined)
+            qs.set('limit', String(params.limit));
+        if (params?.offset !== undefined)
+            qs.set('offset', String(params.offset));
+        const body = await this.client.request(`/v1/admin/organizations${qs.toString() ? '?' + qs : ''}`);
+        return { organizations: body.organizations ?? [], total: body.total ?? 0 };
+    }
+    async create(params) {
+        const body = await this.client.request(`/v1/admin/organizations`, {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+        return body.organization;
+    }
+    async delete(orgId) {
+        await this.client.request(`/v1/admin/organizations/${encodeURIComponent(orgId)}`, { method: 'DELETE' });
+    }
+    async addMember(orgId, params) {
+        await this.client.request(`/v1/admin/organizations/${encodeURIComponent(orgId)}/memberships`, {
+            method: 'POST',
+            body: JSON.stringify({ userId: params.userId, role: params.role ?? 'member' }),
+        });
+    }
+    async removeMember(orgId, userId) {
+        await this.client.request(`/v1/admin/organizations/${encodeURIComponent(orgId)}/memberships/${encodeURIComponent(userId)}`, { method: 'DELETE' });
+    }
+}
+class InvitationsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async create(params) {
+        const body = await this.client.request(`/v1/admin/invitations`, {
+            method: 'POST',
+            body: JSON.stringify({ email: params.email, orgId: params.orgId, role: params.role ?? 'member' }),
+        });
+        return body.invitation;
+    }
+    async revoke(invitationId) {
+        await this.client.request(`/v1/admin/invitations/${encodeURIComponent(invitationId)}`, { method: 'DELETE' });
+    }
+}
+class SessionsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list(params) {
+        const qs = new URLSearchParams();
+        if (params?.userId)
+            qs.set('userId', params.userId);
+        if (params?.limit !== undefined)
+            qs.set('limit', String(params.limit));
+        const body = await this.client.request(`/v1/admin/sessions${qs.toString() ? '?' + qs : ''}`);
+        return { sessions: body.sessions ?? [] };
+    }
+    async revoke(sessionId) {
+        await this.client.request(`/v1/admin/sessions/${encodeURIComponent(sessionId)}/revoke`, {
+            method: 'POST',
+        });
+    }
+}
+/** Factory function — */
+export function createAuthfyioClient(opts) {
+    return new AuthfyioAdminClient(opts);
+}

package/dist/client.d.ts

@@ -0,0 +1,88 @@
+import { type SessionClaims } from './session.js';
+/**
+ * Canonical Authfyio API URL. Customers using the hosted SaaS shouldn't
+ * have to set anything — the default points at production. Override only
+ * when self-hosting or pointing at staging.
+ */
+export declare const DEFAULT_API_BASE_URL = "https://api.authfyio.com";
+export type AuthfyioBackendClientOptions = {
+    /**
+     * Base URL of the instance API. Defaults to `https://api.authfyio.com`
+     * (or `process.env.AF_API_BASE_URL` if set). You only need to override
+     * this when self-hosting.
+     */
+    baseUrl?: string;
+    /**
+     * Optional expected issuer. Matches your API's `AF_JWT_ISSUER`. When
+     * omitted, defaults to `https://api.authfyio.com`.
+     */
+    issuer?: string;
+    /**
+     * Optional expected audience.
+     */
+    audience?: string;
+};
+export type BillingSnapshot = {
+    plan: {
+        id: string;
+        key: string | null;
+        name: string;
+    } | null;
+    features: Array<{
+        key: string;
+        name: string;
+        description?: string;
+    }>;
+    status: string | null;
+};
+export type HasCheck = {
+    plan?: string;
+    feature?: string;
+    role?: string;
+};
+export declare class AuthfyioBackendClient {
+    private opts;
+    constructor(opts: AuthfyioBackendClientOptions);
+    getJwksUrl(): string;
+    private get baseUrl();
+    verifySessionJwt(token: string): Promise<SessionClaims>;
+    /**
+     * Extracts `__session` JWT from a Node/Express/Next request-like object and verifies it.
+     */
+    getSessionFromRequest(req: {
+        headers?: {
+            cookie?: string;
+        };
+    }): Promise<SessionClaims | null>;
+    /**
+     * Fetches the current user's active plan + feature list from the instance
+     * API. Backs server-side `auth().has({ plan, feature })` in route handlers.
+     * Forwards the caller's `__session` cookie so the API can identify them.
+     */
+    fetchMyBilling(req: {
+        headers?: {
+            cookie?: string;
+        };
+    }): Promise<BillingSnapshot | null>;
+    /**
+     * One-shot server-side auth snapshot: verifies the session, fetches the
+     * caller's billing, and returns a customisable object with a `has()`
+     * helper. Use inside route handlers / RSC / server actions:
+     *
+     *   const { userId, has } = await af.auth(req);
+     *   if (!has({ feature: 'pro_export' })) return forbidden();
+     */
+    auth(req: {
+        headers?: {
+            cookie?: string;
+        };
+    }): Promise<{
+        userId: string | null;
+        sessionId: string | null;
+        orgId: string | null;
+        orgRole: string | null;
+        isSignedIn: boolean;
+        has: (check: HasCheck) => boolean;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,aAAa,EAAgC,MAAM,cAAc,CAAC;AAElG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAUF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9D,QAAQ,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,qBAAa,qBAAqB;IAChC,OAAO,CAAC,IAAI,CAA+B;gBAE/B,IAAI,EAAE,4BAA4B;IAI9C,UAAU;IAIV,OAAO,KAAK,OAAO,GAElB;IAEK,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAS7D;;OAEG;IACG,qBAAqB,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAOlG;;;;OAIG;IACG,cAAc,CAClB,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACrC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IA+BlC;;;;;;;OAOG;IACG,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC;QAC1D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,UAAU,EAAE,OAAO,CAAC;QACpB,GAAG,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC;KACnC,CAAC;CA2BH"}

package/dist/client.js

@@ -0,0 +1,114 @@
+import { getSessionJwtFromCookieHeader } from './cookies.js';
+import { verifySessionJwt } from './session.js';
+/**
+ * Canonical Authfyio API URL. Customers using the hosted SaaS shouldn't
+ * have to set anything — the default points at production. Override only
+ * when self-hosting or pointing at staging.
+ */
+export const DEFAULT_API_BASE_URL = 'https://api.authfyio.com';
+function resolveBaseUrl(opts) {
+    return (opts.baseUrl ??
+        (typeof process !== 'undefined' ? process.env?.AF_API_BASE_URL : undefined) ??
+        DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+}
+export class AuthfyioBackendClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    getJwksUrl() {
+        return `${resolveBaseUrl(this.opts)}/.well-known/jwks.json`;
+    }
+    get baseUrl() {
+        return resolveBaseUrl(this.opts);
+    }
+    async verifySessionJwt(token) {
+        const verifyOpts = {
+            jwksUrl: this.getJwksUrl(),
+            issuer: this.opts.issuer,
+            audience: this.opts.audience,
+        };
+        return await verifySessionJwt(token, verifyOpts);
+    }
+    /**
+     * Extracts `__session` JWT from a Node/Express/Next request-like object and verifies it.
+     */
+    async getSessionFromRequest(req) {
+        const cookieHeader = req?.headers?.cookie ?? null;
+        const token = getSessionJwtFromCookieHeader(cookieHeader);
+        if (!token)
+            return null;
+        return await this.verifySessionJwt(token);
+    }
+    /**
+     * Fetches the current user's active plan + feature list from the instance
+     * API. Backs server-side `auth().has({ plan, feature })` in route handlers.
+     * Forwards the caller's `__session` cookie so the API can identify them.
+     */
+    async fetchMyBilling(req) {
+        const cookieHeader = req?.headers?.cookie ?? '';
+        const res = await fetch(`${this.baseUrl}/v1/billing/me`, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+                ...(cookieHeader ? { cookie: cookieHeader } : {}),
+            },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body)
+            return null;
+        return {
+            plan: body.plan
+                ? { id: String(body.plan.id), key: body.plan.key ?? null, name: String(body.plan.name ?? '') }
+                : null,
+            features: Array.isArray(body.features)
+                ? body.features.map((f) => ({
+                    key: String(f.key),
+                    name: String(f.name ?? f.key),
+                    description: f.description ?? undefined,
+                }))
+                : [],
+            status: body.status ?? null,
+        };
+    }
+    /**
+     * One-shot server-side auth snapshot: verifies the session, fetches the
+     * caller's billing, and returns a customisable object with a `has()`
+     * helper. Use inside route handlers / RSC / server actions:
+     *
+     *   const { userId, has } = await af.auth(req);
+     *   if (!has({ feature: 'pro_export' })) return forbidden();
+     */
+    async auth(req) {
+        const claims = await this.getSessionFromRequest(req);
+        if (!claims) {
+            return {
+                userId: null,
+                sessionId: null,
+                orgId: null,
+                orgRole: null,
+                isSignedIn: false,
+                has: () => false,
+            };
+        }
+        const billing = await this.fetchMyBilling(req);
+        return {
+            userId: claims.sub ?? null,
+            sessionId: claims.sid ?? null,
+            orgId: claims.org ?? null,
+            orgRole: claims.org_role ?? null,
+            isSignedIn: true,
+            has: (check) => {
+                if (check.role && claims.org_role !== check.role)
+                    return false;
+                if (check.plan && billing?.plan?.key !== check.plan)
+                    return false;
+                if (check.feature && !billing?.features.some((f) => f.key === check.feature))
+                    return false;
+                return true;
+            },
+        };
+    }
+}

package/dist/cookies.d.ts

@@ -0,0 +1,3 @@
+export declare function parseCookieHeader(cookieHeader: string | null | undefined): Record<string, string>;
+export declare function getSessionJwtFromCookieHeader(cookieHeader: string | null | undefined): string | null;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../src/cookies.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYjG;AAED,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGpG"}

package/dist/cookies.js

@@ -0,0 +1,20 @@
+export function parseCookieHeader(cookieHeader) {
+    const out = {};
+    if (!cookieHeader)
+        return out;
+    for (const part of cookieHeader.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const k = part.slice(0, idx).trim();
+        const v = part.slice(idx + 1).trim();
+        if (!k)
+            continue;
+        out[k] = decodeURIComponent(v);
+    }
+    return out;
+}
+export function getSessionJwtFromCookieHeader(cookieHeader) {
+    const cookies = parseCookieHeader(cookieHeader);
+    return cookies.__session ?? null;
+}

package/dist/cookies.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cookies.spec.d.ts.map

package/dist/cookies.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.spec.d.ts","sourceRoot":"","sources":["../src/cookies.spec.ts"],"names":[],"mappings":""}

package/dist/cookies.spec.js

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { getSessionJwtFromCookieHeader, parseCookieHeader } from './cookies.js';
+describe('parseCookieHeader', () => {
+    it('returns an empty object for null or empty headers', () => {
+        expect(parseCookieHeader(null)).toEqual({});
+        expect(parseCookieHeader(undefined)).toEqual({});
+        expect(parseCookieHeader('')).toEqual({});
+    });
+    it('parses a single cookie', () => {
+        expect(parseCookieHeader('foo=bar')).toEqual({ foo: 'bar' });
+    });
+    it('parses multiple cookies separated by "; "', () => {
+        expect(parseCookieHeader('a=1; b=2; c=3')).toEqual({ a: '1', b: '2', c: '3' });
+    });
+    it('url-decodes cookie values', () => {
+        expect(parseCookieHeader('ref=https%3A%2F%2Fexample.com')).toEqual({
+            ref: 'https://example.com',
+        });
+    });
+    it('ignores malformed parts without an equals sign', () => {
+        expect(parseCookieHeader('a=1; junk; b=2')).toEqual({ a: '1', b: '2' });
+    });
+    it('allows values that contain an "=" character', () => {
+        expect(parseCookieHeader('jwt=eyJhbGciOi.payload=.sig')).toEqual({
+            jwt: 'eyJhbGciOi.payload=.sig',
+        });
+    });
+    it('preserves whitespace around names and values', () => {
+        expect(parseCookieHeader('  a = 1 ;  b= 2')).toEqual({ a: '1', b: '2' });
+    });
+});
+describe('getSessionJwtFromCookieHeader', () => {
+    it('returns the __session cookie when present', () => {
+        expect(getSessionJwtFromCookieHeader('__session=abc123')).toBe('abc123');
+    });
+    it('returns null when __session is missing', () => {
+        expect(getSessionJwtFromCookieHeader('__client=xyz')).toBeNull();
+    });
+    it('returns null for empty input', () => {
+        expect(getSessionJwtFromCookieHeader(null)).toBeNull();
+        expect(getSessionJwtFromCookieHeader('')).toBeNull();
+    });
+    it('prefers __session over __client when both exist', () => {
+        expect(getSessionJwtFromCookieHeader('__client=aaa; __session=bbb')).toBe('bbb');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './cookies.js';
+export * from './session.js';
+export * from './client.js';
+export * from './middleware.js';
+export * from './payments.js';
+export * from './webhooks.js';
+export * from './admin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './cookies.js';
+export * from './session.js';
+export * from './client.js';
+export * from './middleware.js';
+export * from './payments.js';
+export * from './webhooks.js';
+export * from './admin.js';

package/dist/middleware.d.ts

@@ -0,0 +1,16 @@
+import type { SessionClaims } from './session.js';
+import { type AuthfyioBackendClientOptions } from './client.js';
+export type RequireSessionResult<TSession = SessionClaims> = {
+    ok: true;
+    session: TSession;
+} | {
+    ok: false;
+    status: 401;
+    reason: 'missing_session' | 'invalid_session';
+};
+export declare function requireSession(req: {
+    headers?: {
+        cookie?: string;
+    };
+}, opts: AuthfyioBackendClientOptions): Promise<RequireSessionResult>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAAyB,KAAK,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAEvF,MAAM,MAAM,oBAAoB,CAAC,QAAQ,GAAG,aAAa,IACrD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAE9E,wBAAsB,cAAc,CAClC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACtC,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAS/B"}

package/dist/middleware.js

@@ -0,0 +1,13 @@
+import { AuthfyioBackendClient } from './client.js';
+export async function requireSession(req, opts) {
+    const af = new AuthfyioBackendClient(opts);
+    try {
+        const session = await af.getSessionFromRequest(req);
+        if (!session)
+            return { ok: false, status: 401, reason: 'missing_session' };
+        return { ok: true, session };
+    }
+    catch {
+        return { ok: false, status: 401, reason: 'invalid_session' };
+    }
+}

package/dist/payments.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Backend SDK helpers for Authfyio's Stripe-Connect-mediated payments.
+ *
+ * The recommended flow is:
+ *   1. End-user's browser → developer's frontend → Authfyio /v1/payments/intents
+ *      (cookie-authenticated). The browser calls Authfyio directly so the
+ *      developer's backend never has to forward Stripe's client_secret.
+ *
+ *   2. The frontend confirms the PaymentIntent with Stripe.js using the
+ *      developer's *connected* account context:
+ *
+ *        const stripe = await loadStripe(YOUR_PLATFORM_PUBLISHABLE_KEY, {
+ *          stripeAccount: response.publishableKeyAccountId,
+ *        });
+ *        await stripe.confirmCardPayment(response.clientSecret, …);
+ *
+ *   3. Authfyio webhooks update the payment row server-side. The developer's
+ *      backend can then either subscribe to the Authfyio webhook ("payment.succeeded"
+ *      via WebhookEndpointEntity) or poll `getPayment()` below.
+ *
+ * This module exposes a thin server-side helper for case (3) and for backends
+ * that need to issue refunds programmatically.
+ */
+export type PaymentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded' | 'refunded' | 'partially_refunded' | 'disputed';
+export type PaymentRow = {
+    id: string;
+    environmentId: string;
+    stripeAccountId: string;
+    stripePaymentIntentId: string;
+    stripeChargeId: string | null;
+    amountCents: number;
+    applicationFeeCents: number;
+    refundedAmountCents: number;
+    refundedFeeCents: number;
+    currency: string;
+    customerEmail: string | null;
+    description: string | null;
+    status: PaymentStatus;
+    feeBpsApplied: number;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreatePaymentIntentOptions = {
+    /** Smallest currency unit (cents/kuruş/etc). Must be a positive integer. */
+    amountCents: number;
+    /** ISO three-letter currency code (e.g. 'usd', 'eur', 'try'). */
+    currency: string;
+    description?: string;
+    customerEmail?: string;
+    metadata?: Record<string, string>;
+    /**
+     * Per-charge override of the platform fee in basis points. If omitted, the
+     * Connect-account-level default applies (0.6 %).
+     */
+    feeBpsOverride?: number;
+    /**
+     * Idempotency key passed to Stripe. Use the same key on retries so we never
+     * double-charge.
+     */
+    idempotencyKey?: string;
+};
+export type CreatePaymentIntentResult = {
+    paymentId: string;
+    intentId: string;
+    clientSecret: string | null;
+    publishableKeyAccountId: string;
+    amountCents: number;
+    applicationFeeCents: number;
+    feeBpsApplied: number;
+    currency: string;
+    status: PaymentStatus;
+};
+export type RefundOptions = {
+    amountCents?: number;
+    reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
+};
+export type PaymentsClientOptions = {
+    /** Base URL of the Authfyio instance API, e.g. "http://localhost:3001". */
+    baseUrl: string;
+    /**
+     * Cookie header to forward (the end user's `__session` cookie). This is what
+     * authenticates the request — the same flow as the rest of the FAPI.
+     */
+    cookieHeader: string;
+    /** Optional fetch implementation override (Node 18+ has global fetch). */
+    fetchImpl?: typeof fetch;
+};
+export declare class PaymentsClient {
+    private baseUrl;
+    private cookieHeader;
+    private fetchImpl;
+    constructor(opts: PaymentsClientOptions);
+    /**
+     * Create a payment intent on the developer's connected Stripe account.
+     * Returns the `clientSecret` to hand to Stripe.js.
+     */
+    createIntent(opts: CreatePaymentIntentOptions): Promise<CreatePaymentIntentResult>;
+    /** Refund a payment, in full or in part. */
+    refund(paymentId: string, opts?: RefundOptions): Promise<{
+        refundId: string;
+        status: PaymentStatus;
+        refundedAmountCents: number;
+    }>;
+    /** Page through historical payments for the current environment. */
+    list(opts?: {
+        limit?: number;
+        cursor?: string | null;
+    }): Promise<{
+        items: PaymentRow[];
+        nextCursor: string | null;
+    }>;
+    private request;
+}
+//# sourceMappingURL=payments.d.ts.map

package/dist/payments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments.d.ts","sourceRoot":"","sources":["../src/payments.ts"],"names":[],"mappings":"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"}

package/dist/payments.js

@@ -0,0 +1,81 @@
+/**
+ * Backend SDK helpers for Authfyio's Stripe-Connect-mediated payments.
+ *
+ * The recommended flow is:
+ *   1. End-user's browser → developer's frontend → Authfyio /v1/payments/intents
+ *      (cookie-authenticated). The browser calls Authfyio directly so the
+ *      developer's backend never has to forward Stripe's client_secret.
+ *
+ *   2. The frontend confirms the PaymentIntent with Stripe.js using the
+ *      developer's *connected* account context:
+ *
+ *        const stripe = await loadStripe(YOUR_PLATFORM_PUBLISHABLE_KEY, {
+ *          stripeAccount: response.publishableKeyAccountId,
+ *        });
+ *        await stripe.confirmCardPayment(response.clientSecret, …);
+ *
+ *   3. Authfyio webhooks update the payment row server-side. The developer's
+ *      backend can then either subscribe to the Authfyio webhook ("payment.succeeded"
+ *      via WebhookEndpointEntity) or poll `getPayment()` below.
+ *
+ * This module exposes a thin server-side helper for case (3) and for backends
+ * that need to issue refunds programmatically.
+ */
+export class PaymentsClient {
+    baseUrl;
+    cookieHeader;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.cookieHeader = opts.cookieHeader;
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        if (!this.fetchImpl)
+            throw new Error('PaymentsClient: no global fetch and no fetchImpl supplied');
+    }
+    /**
+     * Create a payment intent on the developer's connected Stripe account.
+     * Returns the `clientSecret` to hand to Stripe.js.
+     */
+    async createIntent(opts) {
+        return this.request('POST', '/v1/payments/intents', opts);
+    }
+    /** Refund a payment, in full or in part. */
+    async refund(paymentId, opts = {}) {
+        return this.request('POST', `/v1/payments/${encodeURIComponent(paymentId)}/refund`, opts);
+    }
+    /** Page through historical payments for the current environment. */
+    async list(opts = {}) {
+        const qs = new URLSearchParams();
+        if (opts.limit)
+            qs.set('limit', String(opts.limit));
+        if (opts.cursor)
+            qs.set('cursor', opts.cursor);
+        const path = `/v1/payments/list${qs.size ? `?${qs.toString()}` : ''}`;
+        return this.request('GET', path);
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                cookie: this.cookieHeader,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // Non-JSON error body — propagate raw text below.
+            }
+        }
+        if (!res.ok) {
+            const msg = parsed?.message ?? parsed?.error ?? text ?? `HTTP ${res.status}`;
+            throw new Error(`Authfyio payments error (${res.status}): ${msg}`);
+        }
+        return parsed;
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,29 @@
+export type SessionClaims = {
+    sid: string;
+    sub: string;
+    env: string;
+    org?: string;
+    org_role?: string;
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+};
+export declare const DEFAULT_JWKS_URL = "https://api.authfyio.com/.well-known/jwks.json";
+export type VerifySessionJwtOptions = {
+    /**
+     * JWKS endpoint to verify the JWT against. Defaults to
+     * `https://api.authfyio.com/.well-known/jwks.json` (the hosted SaaS).
+     * Override only when self-hosting.
+     */
+    jwksUrl?: string;
+    issuer?: string;
+    audience?: string;
+    clockToleranceSeconds?: number;
+};
+/**
+ * Verifies `__session` JWT using the instance JWKS endpoint.
+ * Intended for backend apps integrating Authfyio.
+ */
+export declare function verifySessionJwt(token: string, opts?: VerifySessionJwtOptions): Promise<SessionClaims>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,gBAAgB,mDAAmD,CAAC;AAEjF,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,uBAA4B,GAAG,OAAO,CAAC,aAAa,CAAC,CAQhH"}

package/dist/session.js

@@ -0,0 +1,15 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+export const DEFAULT_JWKS_URL = 'https://api.authfyio.com/.well-known/jwks.json';
+/**
+ * Verifies `__session` JWT using the instance JWKS endpoint.
+ * Intended for backend apps integrating Authfyio.
+ */
+export async function verifySessionJwt(token, opts = {}) {
+    const jwks = createRemoteJWKSet(new URL(opts.jwksUrl ?? DEFAULT_JWKS_URL));
+    const { payload } = await jwtVerify(token, jwks, {
+        issuer: opts.issuer,
+        audience: opts.audience,
+        clockTolerance: opts.clockToleranceSeconds,
+    });
+    return payload;
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Kolay webhook delivery signs each outbound request with:
+ *   signature = base64url(HMAC_SHA256(secret, `${timestamp}.${rawBody}`))
+ *
+ * and sends it alongside:
+ *   x-af-webhook-signature: <sig>
+ *   x-af-webhook-timestamp: <unix seconds>
+ *
+ * This helper recomputes the signature and compares in constant time. It
+ * also rejects timestamps outside a configurable tolerance window so an
+ * attacker can't replay old payloads even if they captured one valid
+ * (body, signature) pair.
+ */
+export type VerifyWebhookSignatureOptions = {
+    secret: string;
+    body: string;
+    signature: string;
+    timestamp: string | number;
+    /** Max age (seconds) the timestamp may have before we reject. Default 300. */
+    toleranceSeconds?: number;
+    /** Override "now" (unix seconds) for deterministic tests. */
+    nowSeconds?: number;
+};
+export type VerifyWebhookSignatureResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: 'timestamp_out_of_range' | 'invalid_signature' | 'malformed_timestamp';
+};
+export declare function verifyWebhookSignature(opts: VerifyWebhookSignatureOptions): VerifyWebhookSignatureResult;
+/**
+ * Convenience wrapper — reads the signature/timestamp headers from a plain
+ * object (express `req.headers`, Next's request headers, etc.) and verifies
+ * against the provided raw body. Throws an error when invalid so the caller
+ * can map it to a 401/400 response directly.
+ */
+export declare function assertWebhookSignature(req: {
+    headers: Record<string, string | string[] | undefined>;
+    rawBody: string;
+    secret: string;
+    toleranceSeconds?: number;
+}): void;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GACpC;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,wBAAwB,GAAG,mBAAmB,GAAG,qBAAqB,CAAA;CAAE,CAAC;AAErG,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,6BAA6B,GAClC,4BAA4B,CAsB9B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,IAAI,CAYP"}

package/dist/webhooks.js

@@ -0,0 +1,52 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export function verifyWebhookSignature(opts) {
+    const tsNum = typeof opts.timestamp === 'number' ? opts.timestamp : Number(opts.timestamp);
+    if (!Number.isFinite(tsNum))
+        return { valid: false, reason: 'malformed_timestamp' };
+    const tolerance = opts.toleranceSeconds ?? 300;
+    const now = opts.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - tsNum) > tolerance) {
+        return { valid: false, reason: 'timestamp_out_of_range' };
+    }
+    const expected = createHmac('sha256', opts.secret)
+        .update(`${tsNum}.${opts.body}`)
+        .digest();
+    let provided;
+    try {
+        provided = Buffer.from(opts.signature, 'base64url');
+    }
+    catch {
+        return { valid: false, reason: 'invalid_signature' };
+    }
+    if (provided.length !== expected.length)
+        return { valid: false, reason: 'invalid_signature' };
+    const ok = timingSafeEqual(expected, provided);
+    return ok ? { valid: true } : { valid: false, reason: 'invalid_signature' };
+}
+/**
+ * Convenience wrapper — reads the signature/timestamp headers from a plain
+ * object (express `req.headers`, Next's request headers, etc.) and verifies
+ * against the provided raw body. Throws an error when invalid so the caller
+ * can map it to a 401/400 response directly.
+ */
+export function assertWebhookSignature(req) {
+    const sig = pickHeader(req.headers, 'x-af-webhook-signature');
+    const ts = pickHeader(req.headers, 'x-af-webhook-timestamp');
+    if (!sig || !ts)
+        throw new Error('missing_webhook_signature_headers');
+    const result = verifyWebhookSignature({
+        secret: req.secret,
+        body: req.rawBody,
+        signature: sig,
+        timestamp: ts,
+        toleranceSeconds: req.toleranceSeconds,
+    });
+    if (!result.valid)
+        throw new Error(`invalid_webhook_signature:${result.reason}`);
+}
+function pickHeader(headers, key) {
+    const v = headers[key] ?? headers[key.toLowerCase()];
+    if (Array.isArray(v))
+        return v[0] ?? null;
+    return v ?? null;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "authfyio-backend",
+  "version": "0.2.1",
+  "description": "Framework-agnostic server-side SDK for Authfyio: session JWT verify, cookie helpers, webhook signature verification, and Stripe payments client.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run --config ../../vitest.config.ts --dir src",
+    "test:watch": "vitest --config ../../vitest.config.ts --dir src",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "jose": "^5.9.6"
+  },
+  "keywords": [
+    "authfyio",
+    "auth",
+    "authentication",
+    "jwt",
+    "webhooks",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://authfyio.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/authfyio/authfyio.git"
+  }
+}