@pisti-paypiller/express 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pisti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @pisti-paypiller/express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pisti for Express 5, shaped like `@clerk/express`. It reads its configuration from environment
+variables, so most apps need two lines:
+
+```ts
+import { pistiMiddleware, getAuth } from "@pisti-paypiller/express";
+
+app.use(pistiMiddleware());
+app.get("/api/me", (req, res) => {
+    const { isAuthenticated, userId } = getAuth(req);
+    if (!isAuthenticated) return res.status(401).end();
+    res.json({ userId });
+});
+```
+
+| Export | What it does | Clerk equivalent |
+| --- | --- | --- |
+| `pistiMiddleware(options?)` | Verifies the token on every request and sets `req.auth`. Refreshes expired session cookies on page loads with the handshake. Never blocks. | `clerkMiddleware()` |
+| `getAuth(req, { acceptsToken? })` | The auth object: `isAuthenticated`, `userId`, `sessionId`, `orgId`, `orgRole`, `orgSlug`, `orgPermissions`, `sessionClaims`, `factorVerificationAge`, `has()`, `getToken()`; or an API key, M2M or OAuth token object when accepted | `getAuth(req, { acceptsToken })` |
+| `requireAuth(options?)` | 401 for signed-out requests (or a redirect for pages), 403 when `permission`, `role` or `reverification` fails. Takes `acceptsToken`. | `requireAuth()` |
+| `pistiClient` | Backend API client from `PISTI_SECRET_KEY`: `await pistiClient.users.getUser(userId)` | `clerkClient` |
+| `verifyWebhook(req)` from `@pisti-paypiller/express/webhooks` | Checks a signed webhook delivery and returns the event | `verifyWebhook(req)` |
+
+Requires Node.js 22.12 or later and Express 5. It is built on
+[`@pisti-paypiller/backend`](../backend/README.md), which works without Express.
+
+## 1. Install and configure
+
+```sh
+npm install @pisti-paypiller/express
+```
+
+Copy the keys from the console (your application → Home and API keys):
+
+```sh
+PISTI_PUBLISHABLE_KEY=pk_test_…                     # required: where to verify tokens
+PISTI_SECRET_KEY=sk_test_…                          # for pistiClient
+PISTI_WEBHOOK_SIGNING_SECRET=whsec_…                # for verifyWebhook
+PISTI_AUTHORIZED_PARTIES=https://app.example.com    # recommended in production
+PISTI_SIGN_IN_URL=/sign-in                          # optional: where requireAuth() sends pages
+PISTI_JWT_KEY="-----BEGIN PUBLIC KEY-----\n…"       # optional: verify without fetching signing keys
+```
+
+Each value can also be passed as an option, for example
+`pistiMiddleware({ publishableKey, authorizedParties })`.
+
+## 2. Protect routes
+
+```ts
+import express from "express";
+import { pistiMiddleware, requireAuth, getAuth, pistiClient } from "@pisti-paypiller/express";
+
+const app = express();
+app.use(express.json());
+app.use(pistiMiddleware());
+
+// Check inside a handler
+app.get("/api/feed", (req, res) => {
+    const { isAuthenticated, userId } = getAuth(req);
+    res.json(isAuthenticated ? personalFeed(userId) : publicFeed());
+});
+
+// Look up the full user with the backend API
+app.get("/api/profile", requireAuth(), async (req, res) => {
+    res.json(await pistiClient.users.getUser(getAuth(req).userId!));
+});
+
+// Organization permissions, roles and a recent sign-in
+app.post("/api/invoices", requireAuth({ permission: "invoices:write" }), createInvoice);
+app.delete("/api/workspace", requireAuth({ role: "owner", reverification: "strict" }), destroy);
+
+// Or the same checks in code
+app.post("/api/payouts", (req, res) => {
+    const auth = getAuth(req);
+    if (!auth.has({ permission: "billing:manage" })) return res.sendStatus(403);
+    if (!auth.has({ reverification: { level: "second_factor", afterMinutes: 10 } }))
+        return res.status(403).json({ code: "reverification_required" });
+    // …
+});
+
+// Server-rendered pages: send signed-out browsers to sign-in instead of a 401
+app.get("/settings", requireAuth({ signInUrl: "/sign-in" }), renderSettings);
+```
+
+The middleware reads the token from the `__session` cookie, which `@pisti-paypiller/react` keeps fresh on
+your app's origin, or from `Authorization: Bearer` for APIs on another domain
+(`useAuthenticatedFetch()` in React sends it). It checks the signature, issuer, expiry, that the
+token belongs to your environment and, when configured, the requesting origin. An expired or
+invalid cookie leaves the request signed out; an invalid bearer token answers 401.
+
+`requireAuth()` answers with RFC 9457 problem details: `401 signed_out`, or `403 forbidden` or
+`reverification_required`. With `signInUrl` (or `PISTI_SIGN_IN_URL`), browser page requests
+are redirected there with `redirect_url` set, and `@pisti-paypiller/react` sends people back after
+sign-in.
+
+Reverification presets match Clerk's: `"strict_mfa"` (both factors within 10 minutes),
+`"strict"` (second factor within 10 minutes, or the first factor for users without
+two-step verification), `"moderate"` (60 minutes), `"lax"` (a day), or
+`{ level: "first_factor" | "second_factor" | "multi_factor", afterMinutes }`.
+
+Session tokens last about 60 seconds, so signing out or revoking a session takes effect within a
+minute. No session store, Redis or sticky sessions are needed.
+
+### Server-rendered pages: the handshake
+
+Session tokens last 60 seconds and the browser SDK refreshes them while the page is open. When
+a visitor returns to a server-rendered page after the cookie expired, `pistiMiddleware()`
+answers the page request with a quick redirect through Pisti (Clerk's handshake) that sets a
+fresh `__session` cookie and comes back to the same URL. Your route only runs once the cookie
+is fresh. API requests are never redirected.
+
+Behind a proxy, set `app.set("trust proxy", …)` (or keep the original `Host` header) so the
+middleware builds the return URL on your public origin.
+
+The middleware never rejects a request, so public routes work whatever credential a client
+sends. `requireAuth()` reports a bad token (`401`) or a verification that could not run (`503`,
+for example an API key without `PISTI_SECRET_KEY`) only for token types the route accepts.
+
+### API keys, M2M and OAuth tokens
+
+Routes accept only session tokens unless they ask for more, like Clerk's `acceptsToken`:
+
+```ts
+// Scripts call as a user with an API key created in <APIKeys /> (verified with PISTI_SECRET_KEY)
+app.get("/api/v1/projects", requireAuth({ acceptsToken: ["session_token", "api_key"] }), (req, res) => {
+    const auth = getAuth(req, { acceptsToken: ["session_token", "api_key"] });
+    res.json(listProjects(auth.userId));
+});
+
+// Another service calls with client credentials from a confidential OAuth application
+app.post("/internal/sync", requireAuth({ acceptsToken: "m2m_token" }), (req, res) => {
+    const { machineId } = getAuth(req, { acceptsToken: "m2m_token" });
+    // …
+});
+```
+
+A machine service gets its M2M token from `POST /connect/token` with
+`grant_type=client_credentials`, its client ID and secret.
+
+## 3. Backend API
+
+```ts
+import { pistiClient, PistiManagementError } from "@pisti-paypiller/express";
+
+const user = await pistiClient.users.getUser(userId);
+const { items, nextCursor } = await pistiClient.users.getUserList({ limit: 50, search: "alex" });
+const total = await pistiClient.users.getCount();
+const { items: sessions } = await pistiClient.sessions.getSessionList({ userId, status: "active" });
+for await (const each of pistiClient.users.getUserListAll()) {
+    // …
+}
+await pistiClient.users.banUser(userId);
+await pistiClient.organizations.createOrganizationInvitation(orgId, { email, roleId });
+```
+
+`pistiClient` is created from `PISTI_SECRET_KEY` and `PISTI_PUBLISHABLE_KEY` the first time you
+use it. See [`@pisti-paypiller/backend`](../backend/README.md#backend-api) for every resource and its errors.
+
+## 4. Webhooks
+
+```ts
+import express from "express";
+import { verifyWebhook } from "@pisti-paypiller/express/webhooks";
+
+// Register before app.use(express.json()) so the body stays raw.
+app.post("/api/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
+    try {
+        const event = await verifyWebhook(req);
+        // Events are typed and thin: read the current user with the backend API.
+        if (event.type === "user.created") await createLocalUser(await pistiClient.users.getUser(event.data.id));
+        res.sendStatus(204);
+    } catch {
+        res.sendStatus(400);
+    }
+});
+```
+
+It checks the HMAC-SHA256 signature and the signed timestamp (five minutes' tolerance) before
+parsing. Pass `{ signingSecret: [current, previous] }` while rotating. Store `event.id` to ignore
+duplicates.
+
+## Deploying
+
+- Set the variables above in your host's environment. Use the production environment's
+  `pk_live_` / `sk_live_` keys; they require HTTPS.
+- Verification is stateless and works on servers, containers and serverless functions alike.
+  Signing keys are fetched once per process and cached.
+- Never send `PISTI_SECRET_KEY` to a browser.
+
+See `sdk.md` in the pisti-docs repository for how the pieces fit, and `pisti-demo`
+in the pisti-examples repository for a working example.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import type { Request, RequestHandler } from "express";
+import { type AcceptsToken, type AnyAuthObject, type AuthObject, type AuthObjectFor, type CheckAuthorizationParams, type PistiClient } from "@pisti-paypiller/backend";
+declare global {
+    namespace Express {
+        interface Request {
+            /** Set by pistiMiddleware(). Prefer getAuth(req). */
+            auth?: AnyAuthObject;
+        }
+    }
+}
+export interface PistiMiddlewareOptions {
+    /** Defaults to `PISTI_PUBLISHABLE_KEY`. */
+    publishableKey?: string | undefined;
+    /** Verifies end users' API keys. Defaults to `PISTI_SECRET_KEY`. */
+    secretKey?: string | undefined;
+    /** Origins allowed to have requested the token. Defaults to `PISTI_AUTHORIZED_PARTIES` (comma-separated). */
+    authorizedParties?: string[] | undefined;
+    /** PEM public key for networkless verification. Defaults to `PISTI_JWT_KEY`. */
+    jwtKey?: string | undefined;
+    /** Session cookie written by @pisti-paypiller/react. Defaults to `__session`. */
+    cookieName?: string | undefined;
+}
+/**
+ * Like Clerk's `clerkMiddleware()`: verifies the session token from the `__session` cookie or an
+ * `Authorization: Bearer` header offline and sets `req.auth`. Bearer API keys, OAuth access tokens
+ * and M2M tokens are verified too; routes choose what they accept with `getAuth(req, { acceptsToken })`.
+ *
+ * When a page request arrives with an expired session cookie, it answers with Clerk's handshake:
+ * a redirect through Pisti that refreshes the cookie and returns to the same URL. Server-rendered
+ * pages therefore never see a signed-in visitor as signed out.
+ *
+ * With no options it reads `PISTI_PUBLISHABLE_KEY`, `PISTI_SECRET_KEY`, `PISTI_JWT_KEY` and
+ * `PISTI_AUTHORIZED_PARTIES`.
+ */
+export declare function pistiMiddleware(options?: PistiMiddlewareOptions): RequestHandler;
+/**
+ * The request's auth object, like Clerk's `getAuth(req)`. By default only session tokens count;
+ * pass `acceptsToken` to allow API keys (`"api_key"`), M2M tokens, OAuth access tokens or `"any"`.
+ */
+export declare function getAuth(req: Request): AuthObject;
+export declare function getAuth<T extends AcceptsToken>(req: Request, options: {
+    acceptsToken: T;
+}): AuthObjectFor<T>;
+export interface RequireAuthOptions extends CheckAuthorizationParams {
+    /**
+     * Where to send signed-out browsers instead of answering 401. Defaults to `PISTI_SIGN_IN_URL`
+     * for requests that accept HTML. The current URL is appended as `redirect_url`.
+     */
+    signInUrl?: string | undefined;
+    /** Which tokens may call the route. Defaults to "session_token". */
+    acceptsToken?: AcceptsToken | undefined;
+}
+/**
+ * Protects a route. Signed-out requests get 401 JSON, or a redirect to the sign-in page for
+ * browser navigations. Optional `permission`, `role` and `reverification` checks answer 403.
+ */
+export declare function requireAuth(options?: RequireAuthOptions): RequestHandler;
+/**
+ * A ready-to-use backend client, like Clerk's `clerkClient`, created on first use from
+ * `PISTI_SECRET_KEY` and `PISTI_PUBLISHABLE_KEY`: `await pistiClient.users.getUser(userId)`.
+ */
+export declare const pistiClient: PistiClient;
+export { createPistiClient, verifyToken, PistiError, PistiManagementError } from "@pisti-paypiller/backend";
+export type { AuthObject, SignedInAuthObject, SignedOutAuthObject, SessionClaims, CheckAuthorizationParams, PistiClient, PistiWebhookEvent, TokenType, AcceptsToken, AnyAuthObject, AuthObjectFor, ApiKeyAuthObject, M2MAuthObject, OAuthAuthObject, } from "@pisti-paypiller/backend";
+//# 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":"AACA,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAY,MAAM,SAAS,CAAC;AAC/E,OAAO,EAOH,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAEnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,CAAC,MAAM,CAAC;IAEX,UAAU,OAAO,CAAC;QACd,UAAU,OAAO;YACb,qDAAqD;YACrD,IAAI,CAAC,EAAE,aAAa,CAAC;SACxB;KACJ;CACJ;AAED,MAAM,WAAW,sBAAsB;IACnC,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,6GAA6G;IAC7G,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACzC,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,CA4BpF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAAC;AAClD,wBAAgB,OAAO,CAAC,CAAC,SAAS,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,YAAY,EAAE,CAAC,CAAA;CAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;AAO9G,MAAM,WAAW,kBAAmB,SAAQ,wBAAwB;IAChE;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,oEAAoE;IACpE,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,cAAc,CA2B5E;AAID;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,WAMxB,CAAC;AAqBH,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5G,YAAY,EACR,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,wBAAwB,EACxB,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,eAAe,GAClB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import { PistiError, acceptedTokenTypes, authenticateRequest, createPistiClient, signedOutAuthObject, unauthenticatedObject, } from "@pisti-paypiller/backend";
+// Why a request's credential failed, kept for requireAuth: the middleware itself never rejects a request, so
+// public routes keep working whatever credential a client sends, and a route reports a failure only for a
+// token type it accepts.
+const failures = new WeakMap();
+/** The kind of credential a request carries, without verifying it. */
+function credentialType(req) {
+    const authorization = req.headers.authorization;
+    if (!authorization?.startsWith("Bearer "))
+        return "session_token";
+    const token = authorization.slice(7).trim();
+    if (token.startsWith("ak_"))
+        return "api_key";
+    try {
+        const payload = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+        return payload.ptyp === "oauth" ? "oauth_token" : payload.ptyp === "m2m" ? "m2m_token" : "session_token";
+    }
+    catch {
+        return "session_token";
+    }
+}
+function absoluteUrl(req) {
+    return `${req.protocol}://${req.get("host")}${req.originalUrl}`;
+}
+function fetchRequest(req) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (typeof value === "string")
+            headers.set(name, value);
+        else if (Array.isArray(value))
+            for (const each of value)
+                headers.append(name, each);
+    }
+    return new globalThis.Request(absoluteUrl(req), { method: req.method === "HEAD" ? "GET" : req.method, headers });
+}
+/**
+ * Like Clerk's `clerkMiddleware()`: verifies the session token from the `__session` cookie or an
+ * `Authorization: Bearer` header offline and sets `req.auth`. Bearer API keys, OAuth access tokens
+ * and M2M tokens are verified too; routes choose what they accept with `getAuth(req, { acceptsToken })`.
+ *
+ * When a page request arrives with an expired session cookie, it answers with Clerk's handshake:
+ * a redirect through Pisti that refreshes the cookie and returns to the same URL. Server-rendered
+ * pages therefore never see a signed-in visitor as signed out.
+ *
+ * With no options it reads `PISTI_PUBLISHABLE_KEY`, `PISTI_SECRET_KEY`, `PISTI_JWT_KEY` and
+ * `PISTI_AUTHORIZED_PARTIES`.
+ */
+export function pistiMiddleware(options = {}) {
+    // Fail at startup, not on the first request, when the key is missing or malformed.
+    createPistiClient(options.publishableKey ? { publishableKey: options.publishableKey } : {});
+    return async (req, res, next) => {
+        try {
+            const state = await authenticateRequest(fetchRequest(req), { ...options, acceptsToken: "any" });
+            if (state.status === "handshake") {
+                for (const value of state.headers.getSetCookie())
+                    res.append("Set-Cookie", value);
+                res.setHeader("Cache-Control", "no-store");
+                res.redirect(307, state.headers.get("Location"));
+                return;
+            }
+            // A bad cookie is normal between refreshes; a bad bearer token is reported by routes that require auth.
+            if (state.reason === "token-invalid" && req.headers.authorization?.startsWith("Bearer "))
+                failures.set(req, {
+                    error: new PistiError(401, state.message ?? "The token is invalid.", "invalid_token"),
+                    tokenType: credentialType(req),
+                });
+            req.auth = state.toAuth();
+            next();
+        }
+        catch (error) {
+            // Verification could not run (Pisti unreachable, or API keys without a secret key). Public routes still
+            // work; routes that require auth answer 503.
+            failures.set(req, { error, tokenType: credentialType(req) });
+            req.auth = signedOutAuthObject;
+            next();
+        }
+    };
+}
+export function getAuth(req, options) {
+    if (!req.auth)
+        throw new Error("Add app.use(pistiMiddleware()) before routes that call getAuth(req).");
+    const types = acceptedTokenTypes(options?.acceptsToken);
+    return types.includes(req.auth.tokenType) ? req.auth : unauthenticatedObject(types[0] ?? "session_token");
+}
+/**
+ * Protects a route. Signed-out requests get 401 JSON, or a redirect to the sign-in page for
+ * browser navigations. Optional `permission`, `role` and `reverification` checks answer 403.
+ */
+export function requireAuth(options = {}) {
+    return (req, res, next) => {
+        const acceptsToken = options.acceptsToken ?? "session_token";
+        const auth = getAuth(req, { acceptsToken });
+        const failure = failures.get(req);
+        if (!auth.isAuthenticated && failure && acceptedTokenTypes(acceptsToken).includes(failure.tokenType))
+            return sendProblem(req, res, failure.error);
+        if (!auth.isAuthenticated) {
+            const signInUrl = options.signInUrl ?? process.env.PISTI_SIGN_IN_URL;
+            if (signInUrl && req.method === "GET" && req.accepts(["html", "json"]) === "html") {
+                const origin = `${req.protocol}://${req.get("host")}`;
+                const target = new URL(signInUrl, origin);
+                target.searchParams.set("redirect_url", new URL(req.originalUrl, origin).href);
+                return res.redirect(307, target.origin === origin ? target.pathname + target.search : target.href);
+            }
+            return sendProblem(req, res, new PistiError(401, "Sign in to continue.", "signed_out"));
+        }
+        const { permission, role, reverification } = options;
+        if (auth.tokenType === "session_token") {
+            if ((permission || role) && !auth.has({ permission, role }))
+                return sendProblem(req, res, new PistiError(403, "You don’t have permission to do this.", "forbidden"));
+            if (reverification && !auth.has({ reverification }))
+                return sendProblem(req, res, new PistiError(403, "Confirm it’s you to continue.", "reverification_required"));
+        }
+        else if (permission || role || reverification)
+            return sendProblem(req, res, new PistiError(403, "This route needs a signed-in user.", "forbidden"));
+        next();
+    };
+}
+let shared;
+/**
+ * A ready-to-use backend client, like Clerk's `clerkClient`, created on first use from
+ * `PISTI_SECRET_KEY` and `PISTI_PUBLISHABLE_KEY`: `await pistiClient.users.getUser(userId)`.
+ */
+export const pistiClient = new Proxy({}, {
+    get(_target, property) {
+        shared ??= createPistiClient();
+        const value = Reflect.get(shared, property, shared);
+        return typeof value === "function" ? value.bind(shared) : value;
+    },
+});
+function sendProblem(req, res, error) {
+    const status = error instanceof PistiError ? error.status : 503;
+    const requestId = randomUUID();
+    res.setHeader("X-Request-ID", requestId);
+    res.setHeader("Cache-Control", "no-store");
+    if (status === 401)
+        res.setHeader("WWW-Authenticate", "Bearer");
+    res.status(status)
+        .type("application/problem+json")
+        .json({
+        type: "about:blank",
+        status,
+        title: status === 401 ? "Unauthorized" : status === 403 ? "Forbidden" : "Service Unavailable",
+        detail: error instanceof PistiError ? error.message : "Authentication is temporarily unavailable.",
+        instance: req.path,
+        requestId,
+        ...(error instanceof PistiError && error.code ? { code: error.code } : {}),
+    });
+}
+export { createPistiClient, verifyToken, PistiError, PistiManagementError } from "@pisti-paypiller/backend";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/webhooks.d.ts

@@ -0,0 +1,17 @@
+import type { Request } from "express";
+import { type PistiWebhookEvent, type VerifyWebhookOptions } from "@pisti-paypiller/backend";
+/**
+ * Verifies a webhook delivery, like Clerk's `@clerk/express/webhooks`. Mount the route with
+ * `express.raw({ type: "application/json" })` before `express.json()`. The signing secret
+ * defaults to `PISTI_WEBHOOK_SIGNING_SECRET`.
+ *
+ * ```ts
+ * app.post("/api/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
+ *   const event = await verifyWebhook(req);
+ *   res.sendStatus(204);
+ * });
+ * ```
+ */
+export declare function verifyWebhook(req: Request, options?: VerifyWebhookOptions): Promise<PistiWebhookEvent>;
+export type { PistiWebhookEvent, VerifyWebhookOptions } from "@pisti-paypiller/backend";
+//# 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":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAA2B,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEtH;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CACzB,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,oBAAoB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/webhooks.js

@@ -0,0 +1,17 @@
+import { verifyWebhook as verify } from "@pisti-paypiller/backend";
+/**
+ * Verifies a webhook delivery, like Clerk's `@clerk/express/webhooks`. Mount the route with
+ * `express.raw({ type: "application/json" })` before `express.json()`. The signing secret
+ * defaults to `PISTI_WEBHOOK_SIGNING_SECRET`.
+ *
+ * ```ts
+ * app.post("/api/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
+ *   const event = await verifyWebhook(req);
+ *   res.sendStatus(204);
+ * });
+ * ```
+ */
+export function verifyWebhook(req, options) {
+    return verify({ body: req.body, headers: req.headers }, options);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,IAAI,MAAM,EAAqD,MAAM,0BAA0B,CAAC;AAEtH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CACzB,GAAY,EACZ,OAA8B;IAE9B,OAAO,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@pisti-paypiller/express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.1",
+  "description": "Pisti for Express: pistiMiddleware(), getAuth(req), requireAuth(), pistiClient and webhook verification.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pisti-paypiller/pisti-sdks.git",
+    "directory": "express"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@pisti-paypiller/backend": "0.7.1"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  }
+}