feat: add helpers and improve workspace auth flows

.publish/helpers/README.md

@@ -0,0 +1,60 @@
+# @wrnexus/helpers
+
+Safe convenience helpers for common WrNexus application flows. The package uses
+standard `Context`, `URL`, and `Response` values and has no runtime dependency beyond
+`@wrnexus/core`.
+
+## Installation
+
+```bash
+bun add @wrnexus/helpers
+```
+
+The package is private, so the machine must be authenticated to the `wrnexus` npm
+organization.
+
+## Forward-auth login redirects
+
+The gateway calls an SSO verifier on a different URL from the original application.
+These helpers reconstruct the original URL from the gateway headers and safely place it
+in the login redirect:
+
+```ts
+import type { Context } from "@wrnexus/core";
+import { redirectToLogin } from "@wrnexus/helpers";
+
+export const GET = async (ctx: Context) => {
+  if (await hasValidSession(ctx)) {
+    return new Response(null, { status: 204 });
+  }
+
+  return redirectToLogin(ctx, "/login", {
+    allowedHosts: ["admin.localhost:3000", "reports.localhost:3000"],
+  });
+};
+```
+
+This creates a response such as:
+
+```text
+Location: http://sso.localhost:3000/login?returnTo=http%3A%2F%2Fadmin.localhost%3A3000%2F
+```
+
+Always list the application hosts that are valid redirect destinations. Forwarded host
+headers are rejected when `allowedHosts` is absent or does not match, preventing an open
+redirect. A callback can support dynamic tenant domains:
+
+```ts
+allowedHosts: (host) => host.endsWith(".example.test");
+```
+
+## API
+
+- `getOriginalRequestUrl(ctx, options): URL` — reconstruct the gateway URL.
+- `getOriginalRequestOrigin(ctx, options): string` — return only its origin.
+- `getOriginalRequestPath(ctx): string` — return its path and query string.
+- `getOriginalRequestMethod(ctx): string` — return its HTTP method.
+- `redirectToLogin(ctx, loginUrl, options): Response` — create a login redirect with an
+  encoded `returnTo` parameter.
+
+For direct requests without gateway headers, URL helpers use `ctx.url`.

.publish/helpers/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@wrnexus/helpers",
+  "version": "0.2.17",
+  "type": "module",
+  "description": "Safe convenience helpers for WrNexus request contexts and common application flows.",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "restricted"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@wrnexus/core": "^0.2.17"
+  },
+  "files": [
+    "dist"
+  ]
+}