@xignet/client 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marx Biotech
+
+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,84 @@
-# Temporary Holding Version
+# @xignet/client
 
-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.
+Signet OAuth **machine client** for Node.js. Uses `openid-client` for the
+`client_credentials` protocol and RFC 6749 `client_secret_basic` encoding,
+including client IDs containing colons. Independent of NestJS, Passport, Medusa
+and the existing `@marxbiotech/signet-integration` resource-server package.
+
+Requires Node.js **22.22.0 or newer**. Supports CommonJS `require()` and ESM
+named imports. The CommonJS entry loads the ESM protocol library with native
+dynamic `import()`.
+
+```sh
+npm install @xignet/client
+```
+
+```ts
+import { SignetClient, SignetOAuthError } from '@xignet/client';
+
+const auth = new SignetClient({
+  tokenUrl: process.env.SIGNET_TOKEN_URL!, // token_endpoint from discovery
+  clientId: process.env.SIGNET_CLIENT_ID!, // original ID, NOT pre-encoded
+  clientSecret: process.env.SIGNET_CLIENT_SECRET!,
+  audience: 'https://stocksync.marxbiotech.com/api/mcp',
+  scope: 'stocksync:access',
+  timeoutMs: 30_000, // optional
+});
+
+const token = await auth.getAccessToken();
+// Use Authorization: Bearer <token> with your API client; never add X-API-Key.
+// On API 401, invalidate only the rejected token, then retry at most once:
+auth.invalidateToken(token);
+const replacement = await auth.getAccessToken();
+```
+
+Create one client per credentials/audience/scope configuration and reuse it.
+The cache is process-local; it is not persisted. A request reuses the cached
+token until `expires_in` minus a 60-second margin, capped at half the lifetime
+for short-lived tokens. `refreshMarginSeconds` overrides the margin. Time spent
+obtaining the token counts towards its lifetime. Concurrent exchanges share a
+single promise. Failures clear that promise so a later call can recover.
+
+`audience` and `scope` are sent in the form body. Credentials use Basic auth;
+the caller must pass their original values without pre-encoding them. The token
+URL must use HTTPS and contain no credentials, query or fragment. Redirects
+are rejected. This package uses the explicitly configured token endpoint; it
+does not perform discovery, decode the access token or manage user sessions.
+
+The SDK does **not** retry token failures or make business API requests. API
+401/403 handling belongs to the consumer: invalidate and retry once for 401;
+fail immediately for 403. `invalidateToken(rejectedToken)` cannot evict a newer
+token obtained for another request. There is no refresh token in this flow.
+
+`SignetOAuthError` exposes only `code` and optional HTTP `status`. Codes are
+`INVALID_CONFIGURATION`, `TOKEN_REQUEST_FAILED` and `INVALID_TOKEN_RESPONSE`.
+Raw upstream errors, response bodies and causes are discarded so they cannot
+leak credentials or tokens through application logging. The SDK itself emits no
+logs. The optional `fetch` transport override receives credentials; treat it as
+trusted code, preserve abort handling and do not log request headers or bodies.
+
+## Migrating from @xignet/oauth-client
+
+Replace the package dependency and import source with `@xignet/client`.
+`SignetClient`, `SignetOAuthError`, configuration and runtime behavior are
+unchanged. The previous package remains installable with a deprecation notice.
+
+## Development and release
+
+From the repository root:
+
+```sh
+pnpm install
+pnpm --filter @xignet/client test
+pnpm --filter @xignet/client typecheck
+pnpm --filter @xignet/client build
+```
+
+Releases are independent of the existing root package. Bump this package's
+version and changelog, then push a matching `client-vX.Y.Z` tag. The
+`client-publish.yml` GitHub Actions workflow validates, builds, checks the
+packed artifact and publishes to npm with OIDC. Configure its npm Trusted
+Publisher as GitHub owner `marxbiobuilder`, repository `signet-integration`,
+workflow `client-publish.yml`. A first package publication/registration
+and npm organization permissions must be established before relying on OIDC.
+Prereleases are published under their first prerelease identifier, not `latest`.

package/dist/index.cjs

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignetClient = exports.SignetOAuthError = void 0;
+/** Contains no upstream body, URL, credentials, token or raw cause. Safe to log. */
+class SignetOAuthError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(`Signet OAuth: ${code}${status ? ` (HTTP ${status})` : ''}`);
+        this.name = 'SignetOAuthError';
+        this.code = code;
+        this.status = status;
+    }
+}
+exports.SignetOAuthError = SignetOAuthError;
+/**
+ * One instance per client/audience/scope configuration. Holds a single token in
+ * process memory. No timers, persistent storage, logging or API retries.
+ */
+class SignetClient {
+    #options;
+    #cached;
+    #inFlight;
+    constructor(options) {
+        const invalid = () => new SignetOAuthError('INVALID_CONFIGURATION');
+        for (const value of [
+            options.tokenUrl,
+            options.clientId,
+            options.clientSecret,
+            options.audience,
+            options.scope,
+        ]) {
+            if (typeof value !== 'string' || !value.trim())
+                throw invalid();
+        }
+        let url;
+        try {
+            url = new URL(options.tokenUrl);
+        }
+        catch {
+            throw invalid();
+        }
+        if (url.protocol !== 'https:' ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw invalid();
+        const timeout = options.timeoutMs ?? 30_000;
+        const margin = options.refreshMarginSeconds ?? 60;
+        if (!Number.isSafeInteger(timeout) ||
+            timeout <= 0 ||
+            timeout > 2_147_483_647 ||
+            !Number.isFinite(margin) ||
+            margin < 0 ||
+            (options.fetch !== undefined && typeof options.fetch !== 'function'))
+            throw invalid();
+        this.#options = Object.freeze({
+            ...options,
+            timeoutMs: timeout,
+            refreshMarginSeconds: margin,
+        });
+    }
+    async getAccessToken() {
+        if (this.#cached && Date.now() < this.#cached.expiresAt)
+            return this.#cached.value;
+        if (this.#inFlight)
+            return this.#inFlight;
+        // A finally on the shared promise avoids rejected promises being retained.
+        this.#inFlight = this.#requestToken().finally(() => {
+            this.#inFlight = undefined;
+        });
+        return this.#inFlight;
+    }
+    /**
+     * Invalidate only the rejected token. A late 401 must not evict a newer token
+     * already obtained for another request. Does not cancel an in-flight exchange.
+     */
+    invalidateToken(rejectedToken) {
+        if (this.#cached?.value === rejectedToken)
+            this.#cached = undefined;
+    }
+    async #requestToken() {
+        let status;
+        try {
+            // Keep ESM import native in the CommonJS build for Node.js >=22.22.
+            const oidc = await import('openid-client');
+            const options = this.#options;
+            const config = new oidc.Configuration({
+                issuer: new URL(options.tokenUrl).origin,
+                token_endpoint: options.tokenUrl,
+            }, options.clientId, { token_endpoint_auth_method: 'client_secret_basic' }, oidc.ClientSecretBasic(options.clientSecret));
+            // The protocol library uses redirect:error. Preserve it to avoid forwarding
+            // credentials to redirected endpoints; share a deadline across transport.
+            const signal = AbortSignal.timeout(options.timeoutMs);
+            const transport = options.fetch ?? globalThis.fetch;
+            config[oidc.customFetch] = async (url, init) => {
+                // This SDK only performs form-encoded client credentials requests.
+                if (!(init.body instanceof URLSearchParams)) {
+                    throw new SignetOAuthError('TOKEN_REQUEST_FAILED');
+                }
+                const response = await transport(url, {
+                    ...init,
+                    body: init.body,
+                    redirect: 'error',
+                    signal,
+                });
+                status = response.status;
+                return response;
+            };
+            const requestedAt = Date.now();
+            const data = await oidc.clientCredentialsGrant(config, {
+                audience: options.audience,
+                scope: options.scope,
+            });
+            if (!data.access_token ||
+                /\s/.test(data.access_token) ||
+                data.token_type.toLowerCase() !== 'bearer' ||
+                typeof data.expires_in !== 'number' ||
+                !Number.isFinite(data.expires_in) ||
+                data.expires_in <= 0)
+                throw new SignetOAuthError('INVALID_TOKEN_RESPONSE');
+            const margin = Math.min(options.refreshMarginSeconds, data.expires_in / 2);
+            const expiresAt = requestedAt + (data.expires_in - margin) * 1000;
+            if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+                throw new SignetOAuthError('INVALID_TOKEN_RESPONSE');
+            }
+            this.#cached = { value: data.access_token, expiresAt };
+            return data.access_token;
+        }
+        catch (error) {
+            if (error instanceof SignetOAuthError)
+                throw error;
+            // Discard openid-client errors: cause/response/error_description may be sensitive.
+            throw new SignetOAuthError(status === 200 ? 'INVALID_TOKEN_RESPONSE' : 'TOKEN_REQUEST_FAILED', status);
+        }
+    }
+}
+exports.SignetClient = SignetClient;

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+export interface SignetClientOptions {
+    /** Explicit token_endpoint from the issuer's discovery document. HTTPS only. */
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** Signet/Hydra expects audience in the form body, not resource or query. */
+    audience: string;
+    /** Required: use the scopes configured for this resource/client. */
+    scope: string;
+    timeoutMs?: number;
+    refreshMarginSeconds?: number;
+    /** Optional transport override for proxy integration and isolated tests. */
+    fetch?: typeof globalThis.fetch;
+}
+export type SignetOAuthErrorCode = 'INVALID_CONFIGURATION' | 'TOKEN_REQUEST_FAILED' | 'INVALID_TOKEN_RESPONSE';
+/** Contains no upstream body, URL, credentials, token or raw cause. Safe to log. */
+export declare class SignetOAuthError extends Error {
+    readonly code: SignetOAuthErrorCode;
+    readonly status?: number;
+    constructor(code: SignetOAuthErrorCode, status?: number);
+}
+/**
+ * One instance per client/audience/scope configuration. Holds a single token in
+ * process memory. No timers, persistent storage, logging or API retries.
+ */
+export declare class SignetClient {
+    #private;
+    constructor(options: SignetClientOptions);
+    getAccessToken(): Promise<string>;
+    /**
+     * Invalidate only the rejected token. A late 401 must not evict a newer token
+     * already obtained for another request. Does not cancel an in-flight exchange.
+     */
+    invalidateToken(rejectedToken: string): void;
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@xignet/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.0",
+  "description": "Signet machine-to-machine OAuth client with safe errors, token caching and client_secret_basic authentication.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marxbiobuilder/signet-integration.git",
+    "directory": "packages/client"
+  },
+  "type": "commonjs",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "openid-client": "^6.8.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}