@poly-x/sdk 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,50 @@
+# @poly-x/sdk
+
+PolyX for your **Node backend** — the server-side client that verifies a caller's
+session and tells you who they are. Uses your `sk_…` secret key (never a
+publishable key; it throws if you pass one).
+
+## Install
+
+```bash
+npm install @poly-x/sdk
+```
+
+## Quickstart
+
+```ts
+import { createPolyX } from "@poly-x/sdk";
+
+const polyx = createPolyX({ secretKey: process.env.POLYX_SECRET_KEY });
+
+// Introspect an access token → typed authorization context
+const ctx = await polyx.auth.introspect(accessToken);
+if (ctx.active) {
+  console.log(ctx.userId, ctx.organizationId, ctx.roles);
+}
+```
+
+Guard Express/Connect routes (no Express dependency — the middleware is typed
+structurally):
+
+```ts
+app.get("/me", polyx.express.requireUser(), (req, res) => {
+  res.json(req.polyUser); // { userId, organizationId, role, roles, … }
+});
+```
+
+Or use the framework-agnostic guard directly:
+
+```ts
+const user = await polyx.requireUser(request); // any { headers } request
+```
+
+All guards are **fail-closed**: an unauthenticated caller gets `401`, and an
+upstream/PolyX failure gets `503` (distinct, never silently allowed).
+
+## Exports
+
+`createPolyX` · `requireUser` · `createExpressAdapter` · `introspectToken` ·
+`IntrospectionResult`.
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,172 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _poly_x_core = require("@poly-x/core");
+//#region src/config.ts
+function resolveServerConfig(options = {}) {
+	const secretKey = options.secretKey ?? process.env.POLYX_SECRET_KEY;
+	if (!secretKey) throw new Error("PolyX: missing secret key (set POLYX_SECRET_KEY or pass { secretKey }).");
+	const config = (0, _poly_x_core.resolveConfig)({
+		key: secretKey,
+		baseUrl: options.baseUrl,
+		context: "server"
+	});
+	if (config.kind !== "sk") throw new Error("PolyX: @poly-x/sdk needs a secret key (sk_…); a publishable key (pk_…) was provided.");
+	return {
+		config,
+		transport: options.transport ?? new _poly_x_core.FetchTransport(),
+		secretKey
+	};
+}
+//#endregion
+//#region src/endpoints.ts
+/** Server-side PolyX endpoint paths (relative to the deployment base URL). */
+const SERVER_ENDPOINTS = { introspect: "/v1/authz/introspect" };
+/** Header carrying the App secret key — the v4 requireAppKey contract (ADR-0008). */
+const SECRET_KEY_HEADER = "X-PolyX-Secret-Key";
+//#endregion
+//#region src/introspect.ts
+/**
+* Token introspection (F008) — the server-side "is this caller's session
+* valid, and who are they" check. Wraps poly-auth's `POST /v1/authz/introspect`
+* and normalizes its authz body into a stable `IntrospectionResult`.
+*/
+function asRecord(value) {
+	return value && typeof value === "object" ? value : {};
+}
+function stringOrUndefined(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function normalizeIntrospection(body) {
+	const b = asRecord(body);
+	if (!(b.active === true)) return {
+		active: false,
+		roles: [],
+		raw: body
+	};
+	const rolesRaw = b.organizationRoles;
+	return {
+		active: true,
+		userId: stringOrUndefined(b.userId),
+		organizationId: stringOrUndefined(b.organizationId) ?? stringOrUndefined(b.tenantId),
+		sessionId: stringOrUndefined(b.sessionId),
+		role: stringOrUndefined(b.role),
+		roles: Array.isArray(rolesRaw) ? rolesRaw.filter((r) => typeof r === "string") : [],
+		raw: body
+	};
+}
+async function introspectToken(deps, token) {
+	const response = await deps.transport.request({
+		method: "POST",
+		url: deps.config.baseUrl + SERVER_ENDPOINTS.introspect,
+		headers: { [SECRET_KEY_HEADER]: deps.secretKey },
+		body: { token }
+	});
+	if (response.status === 200) return normalizeIntrospection(response.body);
+	if (response.status === 401) return {
+		active: false,
+		roles: [],
+		raw: response.body
+	};
+	const error = (0, _poly_x_core.mapPlatformError)({
+		status: response.status,
+		body: response.body,
+		headers: response.headers
+	});
+	throw error instanceof _poly_x_core.UpstreamError ? error : new _poly_x_core.UpstreamError("PolyX introspection failed.", {
+		code: "INTROSPECT_FAILED",
+		meta: { status: response.status }
+	});
+}
+//#endregion
+//#region src/require-user.ts
+/**
+* Framework-agnostic request guard (F008). Extracts the bearer token, verifies
+* it via introspection, and yields an authenticated context — fail-closed:
+* missing/invalid token or an upstream failure both deny.
+*/
+function extractBearerToken(request) {
+	const raw = request.headers["authorization"] ?? request.headers["Authorization"];
+	const header = Array.isArray(raw) ? raw[0] : raw;
+	if (!header) return null;
+	const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+	return match ? match[1].trim() : null;
+}
+async function requireUser(deps, request) {
+	const token = extractBearerToken(request);
+	if (!token) throw new _poly_x_core.UnauthenticatedError("Missing bearer token.", {
+		code: "TOKEN_REQUIRED",
+		refreshable: false
+	});
+	const introspection = await introspectToken(deps, token);
+	if (!introspection.active || !introspection.userId) throw new _poly_x_core.UnauthenticatedError("Session is not active.", {
+		code: "UNAUTHENTICATED",
+		refreshable: false
+	});
+	return {
+		userId: introspection.userId,
+		organizationId: introspection.organizationId,
+		sessionId: introspection.sessionId,
+		role: introspection.role,
+		roles: introspection.roles,
+		introspection
+	};
+}
+//#endregion
+//#region src/express.ts
+/**
+* Express/Connect adapter (F008), typed structurally so @poly-x/sdk needs no
+* Express dependency. `requireUser()` attaches `req.polyUser` or fails closed
+* with a 401.
+*/
+function createExpressAdapter(deps) {
+	return { requireUser() {
+		return async (req, res, next) => {
+			try {
+				req.polyUser = await requireUser(deps, req);
+				next();
+			} catch (error) {
+				const code = error instanceof _poly_x_core.PolyXError ? error.code : "UNAUTHENTICATED";
+				const status = error instanceof _poly_x_core.UpstreamError ? 503 : 401;
+				res.status(status).json({ error: code });
+			}
+		};
+	} };
+}
+//#endregion
+//#region src/client.ts
+/**
+* The unified server client (F008). v1 ships the auth slice: token
+* introspection + request guards. Notifications/logs/api pillars namespace in
+* here later (the Clerk-style unified shape).
+*/
+function createPolyX(options = {}) {
+	const resolved = resolveServerConfig(options);
+	const deps = {
+		config: resolved.config,
+		transport: resolved.transport,
+		secretKey: resolved.secretKey
+	};
+	return {
+		auth: { introspect: (token) => introspectToken(deps, token) },
+		express: createExpressAdapter(deps),
+		requireUser: (request) => requireUser(deps, request)
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @poly-x/sdk — the server-side client for consuming Node backends (the `sk_`
+* key side). v1 ships the auth slice: introspection + request guards.
+*/
+const PACKAGE_NAME = "@poly-x/sdk";
+const version = "0.0.0";
+//#endregion
+exports.PACKAGE_NAME = PACKAGE_NAME;
+exports.SECRET_KEY_HEADER = SECRET_KEY_HEADER;
+exports.SERVER_ENDPOINTS = SERVER_ENDPOINTS;
+exports.createExpressAdapter = createExpressAdapter;
+exports.createPolyX = createPolyX;
+exports.extractBearerToken = extractBearerToken;
+exports.introspectToken = introspectToken;
+exports.normalizeIntrospection = normalizeIntrospection;
+exports.requireUser = requireUser;
+exports.version = version;

package/dist/index.d.cts

@@ -0,0 +1,88 @@
+import { ResolvedConfig, Transport } from "@poly-x/core";
+
+//#region src/config.d.ts
+interface PolyXOptions {
+  /** The `sk_…` secret key. Default source: `POLYX_SECRET_KEY`. */
+  secretKey?: string;
+  baseUrl?: string;
+  /** Advanced: inject a transport (tests supply a mock). */
+  transport?: Transport;
+}
+//#endregion
+//#region src/introspect.d.ts
+interface IntrospectionResult {
+  active: boolean;
+  userId?: string;
+  organizationId?: string;
+  sessionId?: string;
+  role?: string;
+  roles: readonly string[];
+  /** The raw platform body, for fields not surfaced here. */
+  raw: unknown;
+}
+declare function normalizeIntrospection(body: unknown): IntrospectionResult;
+interface IntrospectDeps {
+  config: ResolvedConfig;
+  transport: Transport;
+  secretKey: string;
+}
+declare function introspectToken(deps: IntrospectDeps, token: string): Promise<IntrospectionResult>;
+//#endregion
+//#region src/require-user.d.ts
+interface AuthenticatedContext {
+  userId: string;
+  organizationId?: string;
+  sessionId?: string;
+  role?: string;
+  roles: readonly string[];
+  introspection: IntrospectionResult;
+}
+/** A minimal, structural request shape — compatible with Express/Fetch/Node. */
+interface HeaderCarrier {
+  headers: Record<string, string | string[] | undefined>;
+}
+declare function extractBearerToken(request: HeaderCarrier): string | null;
+declare function requireUser(deps: IntrospectDeps, request: HeaderCarrier): Promise<AuthenticatedContext>;
+//#endregion
+//#region src/express.d.ts
+interface ExpressLikeRequest {
+  headers: Record<string, string | string[] | undefined>;
+  polyUser?: AuthenticatedContext;
+}
+interface ExpressLikeResponse {
+  status(code: number): ExpressLikeResponse;
+  json(body: unknown): unknown;
+}
+type ExpressLikeNext = (error?: unknown) => void;
+declare function createExpressAdapter(deps: IntrospectDeps): {
+  requireUser(): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: ExpressLikeNext) => Promise<void>;
+};
+//#endregion
+//#region src/client.d.ts
+interface PolyX {
+  auth: {
+    introspect(token: string): Promise<IntrospectionResult>;
+  };
+  express: ReturnType<typeof createExpressAdapter>;
+  /** Framework-agnostic guard for non-Express servers. */
+  requireUser(request: HeaderCarrier): Promise<AuthenticatedContext>;
+}
+declare function createPolyX(options?: PolyXOptions): PolyX;
+//#endregion
+//#region src/endpoints.d.ts
+/** Server-side PolyX endpoint paths (relative to the deployment base URL). */
+declare const SERVER_ENDPOINTS: {
+  readonly introspect: "/v1/authz/introspect";
+};
+/** Header carrying the App secret key — the v4 requireAppKey contract (ADR-0008). */
+declare const SECRET_KEY_HEADER = "X-PolyX-Secret-Key";
+//#endregion
+//#region src/index.d.ts
+/**
+ * @poly-x/sdk — the server-side client for consuming Node backends (the `sk_`
+ * key side). v1 ships the auth slice: introspection + request guards.
+ */
+declare const PACKAGE_NAME = "@poly-x/sdk";
+declare const version = "0.0.0";
+//#endregion
+export { type AuthenticatedContext, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type HeaderCarrier, type IntrospectionResult, PACKAGE_NAME, type PolyX, type PolyXOptions, SECRET_KEY_HEADER, SERVER_ENDPOINTS, createExpressAdapter, createPolyX, extractBearerToken, introspectToken, normalizeIntrospection, requireUser, version };

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+import { ResolvedConfig, Transport } from "@poly-x/core";
+
+//#region src/config.d.ts
+interface PolyXOptions {
+  /** The `sk_…` secret key. Default source: `POLYX_SECRET_KEY`. */
+  secretKey?: string;
+  baseUrl?: string;
+  /** Advanced: inject a transport (tests supply a mock). */
+  transport?: Transport;
+}
+//#endregion
+//#region src/introspect.d.ts
+interface IntrospectionResult {
+  active: boolean;
+  userId?: string;
+  organizationId?: string;
+  sessionId?: string;
+  role?: string;
+  roles: readonly string[];
+  /** The raw platform body, for fields not surfaced here. */
+  raw: unknown;
+}
+declare function normalizeIntrospection(body: unknown): IntrospectionResult;
+interface IntrospectDeps {
+  config: ResolvedConfig;
+  transport: Transport;
+  secretKey: string;
+}
+declare function introspectToken(deps: IntrospectDeps, token: string): Promise<IntrospectionResult>;
+//#endregion
+//#region src/require-user.d.ts
+interface AuthenticatedContext {
+  userId: string;
+  organizationId?: string;
+  sessionId?: string;
+  role?: string;
+  roles: readonly string[];
+  introspection: IntrospectionResult;
+}
+/** A minimal, structural request shape — compatible with Express/Fetch/Node. */
+interface HeaderCarrier {
+  headers: Record<string, string | string[] | undefined>;
+}
+declare function extractBearerToken(request: HeaderCarrier): string | null;
+declare function requireUser(deps: IntrospectDeps, request: HeaderCarrier): Promise<AuthenticatedContext>;
+//#endregion
+//#region src/express.d.ts
+interface ExpressLikeRequest {
+  headers: Record<string, string | string[] | undefined>;
+  polyUser?: AuthenticatedContext;
+}
+interface ExpressLikeResponse {
+  status(code: number): ExpressLikeResponse;
+  json(body: unknown): unknown;
+}
+type ExpressLikeNext = (error?: unknown) => void;
+declare function createExpressAdapter(deps: IntrospectDeps): {
+  requireUser(): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: ExpressLikeNext) => Promise<void>;
+};
+//#endregion
+//#region src/client.d.ts
+interface PolyX {
+  auth: {
+    introspect(token: string): Promise<IntrospectionResult>;
+  };
+  express: ReturnType<typeof createExpressAdapter>;
+  /** Framework-agnostic guard for non-Express servers. */
+  requireUser(request: HeaderCarrier): Promise<AuthenticatedContext>;
+}
+declare function createPolyX(options?: PolyXOptions): PolyX;
+//#endregion
+//#region src/endpoints.d.ts
+/** Server-side PolyX endpoint paths (relative to the deployment base URL). */
+declare const SERVER_ENDPOINTS: {
+  readonly introspect: "/v1/authz/introspect";
+};
+/** Header carrying the App secret key — the v4 requireAppKey contract (ADR-0008). */
+declare const SECRET_KEY_HEADER = "X-PolyX-Secret-Key";
+//#endregion
+//#region src/index.d.ts
+/**
+ * @poly-x/sdk — the server-side client for consuming Node backends (the `sk_`
+ * key side). v1 ships the auth slice: introspection + request guards.
+ */
+declare const PACKAGE_NAME = "@poly-x/sdk";
+declare const version = "0.0.0";
+//#endregion
+export { type AuthenticatedContext, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type HeaderCarrier, type IntrospectionResult, PACKAGE_NAME, type PolyX, type PolyXOptions, SECRET_KEY_HEADER, SERVER_ENDPOINTS, createExpressAdapter, createPolyX, extractBearerToken, introspectToken, normalizeIntrospection, requireUser, version };

package/dist/index.mjs

@@ -0,0 +1,162 @@
+import { FetchTransport, PolyXError, UnauthenticatedError, UpstreamError, mapPlatformError, resolveConfig } from "@poly-x/core";
+//#region src/config.ts
+function resolveServerConfig(options = {}) {
+	const secretKey = options.secretKey ?? process.env.POLYX_SECRET_KEY;
+	if (!secretKey) throw new Error("PolyX: missing secret key (set POLYX_SECRET_KEY or pass { secretKey }).");
+	const config = resolveConfig({
+		key: secretKey,
+		baseUrl: options.baseUrl,
+		context: "server"
+	});
+	if (config.kind !== "sk") throw new Error("PolyX: @poly-x/sdk needs a secret key (sk_…); a publishable key (pk_…) was provided.");
+	return {
+		config,
+		transport: options.transport ?? new FetchTransport(),
+		secretKey
+	};
+}
+//#endregion
+//#region src/endpoints.ts
+/** Server-side PolyX endpoint paths (relative to the deployment base URL). */
+const SERVER_ENDPOINTS = { introspect: "/v1/authz/introspect" };
+/** Header carrying the App secret key — the v4 requireAppKey contract (ADR-0008). */
+const SECRET_KEY_HEADER = "X-PolyX-Secret-Key";
+//#endregion
+//#region src/introspect.ts
+/**
+* Token introspection (F008) — the server-side "is this caller's session
+* valid, and who are they" check. Wraps poly-auth's `POST /v1/authz/introspect`
+* and normalizes its authz body into a stable `IntrospectionResult`.
+*/
+function asRecord(value) {
+	return value && typeof value === "object" ? value : {};
+}
+function stringOrUndefined(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function normalizeIntrospection(body) {
+	const b = asRecord(body);
+	if (!(b.active === true)) return {
+		active: false,
+		roles: [],
+		raw: body
+	};
+	const rolesRaw = b.organizationRoles;
+	return {
+		active: true,
+		userId: stringOrUndefined(b.userId),
+		organizationId: stringOrUndefined(b.organizationId) ?? stringOrUndefined(b.tenantId),
+		sessionId: stringOrUndefined(b.sessionId),
+		role: stringOrUndefined(b.role),
+		roles: Array.isArray(rolesRaw) ? rolesRaw.filter((r) => typeof r === "string") : [],
+		raw: body
+	};
+}
+async function introspectToken(deps, token) {
+	const response = await deps.transport.request({
+		method: "POST",
+		url: deps.config.baseUrl + SERVER_ENDPOINTS.introspect,
+		headers: { [SECRET_KEY_HEADER]: deps.secretKey },
+		body: { token }
+	});
+	if (response.status === 200) return normalizeIntrospection(response.body);
+	if (response.status === 401) return {
+		active: false,
+		roles: [],
+		raw: response.body
+	};
+	const error = mapPlatformError({
+		status: response.status,
+		body: response.body,
+		headers: response.headers
+	});
+	throw error instanceof UpstreamError ? error : new UpstreamError("PolyX introspection failed.", {
+		code: "INTROSPECT_FAILED",
+		meta: { status: response.status }
+	});
+}
+//#endregion
+//#region src/require-user.ts
+/**
+* Framework-agnostic request guard (F008). Extracts the bearer token, verifies
+* it via introspection, and yields an authenticated context — fail-closed:
+* missing/invalid token or an upstream failure both deny.
+*/
+function extractBearerToken(request) {
+	const raw = request.headers["authorization"] ?? request.headers["Authorization"];
+	const header = Array.isArray(raw) ? raw[0] : raw;
+	if (!header) return null;
+	const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+	return match ? match[1].trim() : null;
+}
+async function requireUser(deps, request) {
+	const token = extractBearerToken(request);
+	if (!token) throw new UnauthenticatedError("Missing bearer token.", {
+		code: "TOKEN_REQUIRED",
+		refreshable: false
+	});
+	const introspection = await introspectToken(deps, token);
+	if (!introspection.active || !introspection.userId) throw new UnauthenticatedError("Session is not active.", {
+		code: "UNAUTHENTICATED",
+		refreshable: false
+	});
+	return {
+		userId: introspection.userId,
+		organizationId: introspection.organizationId,
+		sessionId: introspection.sessionId,
+		role: introspection.role,
+		roles: introspection.roles,
+		introspection
+	};
+}
+//#endregion
+//#region src/express.ts
+/**
+* Express/Connect adapter (F008), typed structurally so @poly-x/sdk needs no
+* Express dependency. `requireUser()` attaches `req.polyUser` or fails closed
+* with a 401.
+*/
+function createExpressAdapter(deps) {
+	return { requireUser() {
+		return async (req, res, next) => {
+			try {
+				req.polyUser = await requireUser(deps, req);
+				next();
+			} catch (error) {
+				const code = error instanceof PolyXError ? error.code : "UNAUTHENTICATED";
+				const status = error instanceof UpstreamError ? 503 : 401;
+				res.status(status).json({ error: code });
+			}
+		};
+	} };
+}
+//#endregion
+//#region src/client.ts
+/**
+* The unified server client (F008). v1 ships the auth slice: token
+* introspection + request guards. Notifications/logs/api pillars namespace in
+* here later (the Clerk-style unified shape).
+*/
+function createPolyX(options = {}) {
+	const resolved = resolveServerConfig(options);
+	const deps = {
+		config: resolved.config,
+		transport: resolved.transport,
+		secretKey: resolved.secretKey
+	};
+	return {
+		auth: { introspect: (token) => introspectToken(deps, token) },
+		express: createExpressAdapter(deps),
+		requireUser: (request) => requireUser(deps, request)
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* @poly-x/sdk — the server-side client for consuming Node backends (the `sk_`
+* key side). v1 ships the auth slice: introspection + request guards.
+*/
+const PACKAGE_NAME = "@poly-x/sdk";
+const version = "0.0.0";
+//#endregion
+export { PACKAGE_NAME, SECRET_KEY_HEADER, SERVER_ENDPOINTS, createExpressAdapter, createPolyX, extractBearerToken, introspectToken, normalizeIntrospection, requireUser, version };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@poly-x/sdk",
+  "version": "0.1.0-alpha.0",
+  "description": "PolyX SDK for Node servers - unified client and framework adapters",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "dependencies": {
+    "@poly-x/core": "0.1.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/waiindustries/wAI%20Engineering/_git/poly-x-sdk"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}