@centia-io/sdk 0.0.58 → 0.1.0

package/dist/centia-io-sdk.umd.js

@@ -2570,6 +2570,224 @@
 		};
 	}
 
+//#endregion
+//#region src/auth/errors.ts
+/**
+	* @author     Martin Høgh <mh@mapcentia.com>
+	* @copyright  2013-2026 MapCentia ApS
+	* @license    https://opensource.org/license/mit  The MIT License
+	*
+	*/
+	/**
+	* Thrown by {@link createTokenProvider} when the {@link TokenStore} has no
+	* access token. Indicates the user has never logged in (or has logged out)
+	* and a fresh interactive login is required. Distinct from
+	* {@link SessionExpiredError}, which means the user *did* log in but the
+	* refresh token has since expired.
+	*/
+	var NotLoggedInError = class extends Error {
+		constructor(message = "Not logged in: no access token in store") {
+			super(message);
+			this.name = "NotLoggedInError";
+		}
+	};
+	/**
+	* Thrown by {@link createTokenProvider} when the access token is expired and
+	* the refresh token is either missing or also expired. Indicates the
+	* stored credentials cannot be silently revived; the user must run an
+	* interactive login again.
+	*/
+	var SessionExpiredError = class extends Error {
+		constructor(message = "Session expired: refresh token is missing or expired") {
+			super(message);
+			this.name = "SessionExpiredError";
+		}
+	};
+
+//#endregion
+//#region src/auth/tokenProvider.ts
+/**
+	* @author     Martin Høgh <mh@mapcentia.com>
+	* @copyright  2013-2026 MapCentia ApS
+	* @license    https://opensource.org/license/mit  The MIT License
+	*
+	*/
+	const DEFAULT_SKEW_SECONDS = 30;
+	/**
+	* Build a {@link TokenProvider} that returns a fresh access token, refreshing
+	* via `opts.authService` and persisting the result to `opts.store` whenever
+	* the cached token is within `expirySkewSeconds` of expiry.
+	*
+	* **Behaviour:**
+	* - If the store has no access token, throws {@link NotLoggedInError}.
+	* - If the access token is fresh, returns it immediately.
+	* - If expired and the refresh token is missing or expired, throws
+	*   {@link SessionExpiredError}.
+	* - Otherwise calls `opts.authService.getRefreshToken(refresh_token)`,
+	*   persists `{ token, refresh_token? }` via `opts.store.set()`, and
+	*   returns the new access token.
+	*
+	* **In-process concurrency.** Multiple concurrent `getAccessToken()` calls
+	* during a refresh share a single in-flight promise; the auth service is
+	* called exactly once per refresh cycle. On failure the in-flight slot
+	* clears so the next call retries.
+	*
+	* **Cross-process concurrency — known limitation.** This function does NOT
+	* coordinate refresh across processes. Two processes that share a
+	* configstore-backed {@link TokenStore} can each independently observe an
+	* expired access token, both call `getRefreshToken` against the same
+	* refresh token, and the OAuth provider will reject the second call with
+	* `invalid_grant` once the refresh token rotates. Callers that run
+	* multiple processes concurrently against the same store should treat
+	* `invalid_grant` as a transient failure and re-read the store before
+	* retrying. Closing this gap requires holding the file lock across the
+	* network refresh, which the current implementation does not do.
+	*
+	* @param opts - Provider configuration.
+	* @param opts.store - Where credentials are read from and written to.
+	* @param opts.authService - Object exposing
+	*                           `getRefreshToken(refreshToken)`. The existing
+	*                           `Gc2Service` (returned by `CodeFlow#service`)
+	*                           satisfies this structurally.
+	* @param opts.expirySkewSeconds - How many seconds before `exp` to treat a
+	*                                 JWT as expired. Default `30`.
+	* @returns A {@link TokenProvider} whose `getAccessToken()` resolves to a
+	*          non-expired access token, refreshing if necessary.
+	*/
+	function createTokenProvider(opts) {
+		var _opts$expirySkewSecon;
+		const skew = (_opts$expirySkewSecon = opts.expirySkewSeconds) !== null && _opts$expirySkewSecon !== void 0 ? _opts$expirySkewSecon : DEFAULT_SKEW_SECONDS;
+		let inFlight = null;
+		async function refresh(refreshToken) {
+			const refreshed = await opts.authService.getRefreshToken(refreshToken);
+			const patch = { token: refreshed.access_token };
+			if (refreshed.refresh_token) patch.refresh_token = refreshed.refresh_token;
+			await opts.store.set(patch);
+			return refreshed.access_token;
+		}
+		return { async getAccessToken() {
+			const creds = await opts.store.get();
+			if (!creds.token) throw new NotLoggedInError();
+			if (!isExpired(creds.token, skew)) return creds.token;
+			if (!creds.refresh_token || isExpired(creds.refresh_token, skew)) throw new SessionExpiredError();
+			if (!inFlight) inFlight = refresh(creds.refresh_token).finally(() => {
+				inFlight = null;
+			});
+			return inFlight;
+		} };
+	}
+	function isExpired(jwt, skewSeconds) {
+		const { exp } = jwtDecode(jwt);
+		if (!exp) return false;
+		return Math.floor(Date.now() / 1e3) + skewSeconds >= exp;
+	}
+
+//#endregion
+//#region src/auth/configstoreTokenStore.ts
+	const LOCK_RETRIES = 5;
+	const LOCK_RETRY_MIN_MS = 100;
+	const LOCK_RETRY_MAX_MS = 500;
+	const LOCK_STALE_MS = 1e4;
+	/**
+	* Build a Node-only file-backed {@link TokenStore} that persists OAuth
+	* credentials at `~/.config/configstore/<name>.json` (or
+	* `$XDG_CONFIG_HOME/configstore/<name>.json` if set), with both in-process
+	* and cross-process write safety.
+	*
+	* **Shared-state intent.** The `name` is the file name on disk. Two processes
+	* (e.g. `gc2-cli` and a local MCP server) that pass the same name share the
+	* same on-disk credentials and therefore the same login session. The default
+	* `'gc2-env'` matches the name `gc2-cli` already uses, so a one-time
+	* `gc2 login` is observable to every process that calls
+	* `createConfigstoreTokenStore()` with no argument. Pass a different name
+	* to isolate.
+	*
+	* **In-process correctness.** A serial promise chain on `set()` ensures
+	* concurrent same-process calls do not race on the shared configstore cache.
+	*
+	* **Cross-process correctness.** `proper-lockfile` serializes the
+	* read-merge-write critical section across processes so two simultaneous
+	* `set()` calls from different processes cannot corrupt the file.
+	*
+	* **Node-only.** The dynamic imports keep `configstore` and `proper-lockfile`
+	* out of browser bundles even when this module is imported through the SDK
+	* barrel. Calling this function in a browser environment will fail at
+	* runtime when the deferred `await import('configstore')` cannot resolve.
+	*
+	* @param name - configstore file name (without `.json`). Default `'gc2-env'`
+	*               matches `gc2-cli`'s configstore so credentials are shared.
+	* @returns A {@link TokenStore} suitable for passing to {@link createTokenProvider}.
+	*/
+	function createConfigstoreTokenStore(name = "gc2-env") {
+		let configstoreInstance = null;
+		let setChain = Promise.resolve();
+		async function getConfigstore() {
+			var _default;
+			if (configstoreInstance) return configstoreInstance;
+			const mod = await import("configstore");
+			const Configstore = (_default = mod.default) !== null && _default !== void 0 ? _default : mod;
+			const { homedir } = await import("node:os");
+			const { join } = await import("node:path");
+			configstoreInstance = new Configstore(name, void 0, { configPath: join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "configstore", `${name}.json`) });
+			return configstoreInstance;
+		}
+		async function getLockfile() {
+			var _default2;
+			const mod = await import("proper-lockfile");
+			return (_default2 = mod.default) !== null && _default2 !== void 0 ? _default2 : mod;
+		}
+		function readAll(cs) {
+			const result = {};
+			const token = cs.get("token");
+			const refresh_token = cs.get("refresh_token");
+			const host = cs.get("host");
+			if (token !== void 0) result.token = token;
+			if (refresh_token !== void 0) result.refresh_token = refresh_token;
+			if (host !== void 0) result.host = host;
+			return result;
+		}
+		async function doLockedSet(patch) {
+			const cs = await getConfigstore();
+			const lockfile = await getLockfile();
+			const filePath = cs.path;
+			const { mkdirSync, writeFileSync } = await import("node:fs");
+			const { dirname } = await import("node:path");
+			try {
+				mkdirSync(dirname(filePath), { recursive: true });
+				writeFileSync(filePath, "{}", { flag: "wx" });
+			} catch (e) {
+				if ((e === null || e === void 0 ? void 0 : e.code) !== "EEXIST") throw e;
+			}
+			const release = await lockfile.lock(filePath, {
+				retries: {
+					retries: LOCK_RETRIES,
+					minTimeout: LOCK_RETRY_MIN_MS,
+					maxTimeout: LOCK_RETRY_MAX_MS,
+					factor: 2
+				},
+				stale: LOCK_STALE_MS,
+				realpath: false
+			});
+			try {
+				configstoreInstance = null;
+				const fresh = await getConfigstore();
+				fresh.all = _objectSpread2(_objectSpread2({}, readAll(fresh)), patch);
+			} finally {
+				await release();
+			}
+		}
+		return {
+			async get() {
+				return readAll(await getConfigstore());
+			},
+			async set(patch) {
+				const next = setChain.then(() => doLockedSet(patch));
+				setChain = next.catch(() => {});
+				return next;
+			}
+		};
+	}
+
 //#endregion
 //#region src/index.ts
 /**
@@ -2585,8 +2803,10 @@ exports.Claims = Claims;
 exports.CodeFlow = CodeFlow;
 exports.Gql = Gql;
 exports.Meta = Meta;
+exports.NotLoggedInError = NotLoggedInError;
 exports.PasswordFlow = PasswordFlow;
 exports.Rpc = Rpc;
+exports.SessionExpiredError = SessionExpiredError;
 exports.SignUp = SignUp;
 exports.Sql = Sql;
 exports.SqlNoToken = SqlNoToken;
@@ -2598,6 +2818,8 @@ exports.Ws = Ws;
 exports.createApi = createApi;
 exports.createCentiaAdminClient = createCentiaAdminClient;
 exports.createCentiaClient = createCentiaClient;
+exports.createConfigstoreTokenStore = createConfigstoreTokenStore;
 exports.createSqlBuilder = createSqlBuilder;
+exports.createTokenProvider = createTokenProvider;
 exports.isCentiaApiError = isCentiaApiError;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centia-io/sdk",
-  "version": "0.0.58",
+  "version": "0.1.0",
   "description": "Centia-io TypeScript SDK",
   "author": "Martin Høgh",
   "license": "MIT",
@@ -24,10 +24,20 @@
     "test": "vitest run",
     "test:watch": "vitest"
   },
+  "dependencies": {
+    "configstore": "^7.0.0",
+    "proper-lockfile": "^4.1.2"
+  },
   "devDependencies": {
+    "@types/configstore": "^6.0.2",
+    "@types/proper-lockfile": "^4.1.4",
     "tsdown": "^0.17.3",
+    "tsx": "^4.19.0",
     "typescript": "^5.6.3",
     "vitest": "^4.0.18"
   },
-  "private": false
+  "private": false,
+  "engines": {
+    "node": ">=18"
+  }
 }