@gorth-io/structure 0.0.0-alpha.5

package/dist/utils/formatter.js

@@ -0,0 +1,2 @@
+function e(e){return{subject:e.sub,name:e.name,email:e.email,emailVerified:e.email_verified,username:e.preferred_username,image:e.picture}}function t(e){return e instanceof Date?e.getTime():typeof e==`string`?Date.parse(e):e}function n(e,t,n,r){return{status:e,body:JSON.stringify({error:{message:t,code:n,data:{code:r,httpStatus:e}}})}}function r(e){if(!e.trim())return``;let t=e.split(`+`).map(e=>e.trim()),n=t.pop().replace(/^Arrow/,``);if(!/^(?:[a-z0-9,./;[\]\\-]|Tab|Space|Plus|Enter|Backspace|Delete|Escape|Up|Down|Left|Right|F(?:[1-9]|1[0-9]|2[0-4]))$/i.test(n))throw Error(`Choose a letter, number, function key or navigation key.`);let r=[`CmdOrCtrl`,`Ctrl`,`Alt`,`Shift`,`Super`];if(t.some(e=>!r.includes(e))||new Set(t).size!==t.length||!t.some(e=>[`CmdOrCtrl`,`Ctrl`,`Alt`,`Super`].includes(e))&&!/^F\d+$/i.test(n))throw Error(`Use Command/Control, Alt, or a function key.`);let i=[`Tab`,`Space`,`Plus`,`Enter`,`Backspace`,`Delete`,`Escape`,`Up`,`Down`,`Left`,`Right`];return[...r.filter(e=>t.includes(e)),i.find(e=>e.toLowerCase()===n.toLowerCase())??n.toUpperCase()].join(`+`)}function i(e,t){return e.replace(`CmdOrCtrl`,t?`Super`:`Ctrl`).split(`+`).sort().join(`+`)}function a(e){let t=new Headers;for(let[n,r]of Object.entries(e.headers))if(r!=null&&r!==!1)for(let e of Array.isArray(r)?r:[r])t.append(n,String(e));for(let e of(t.get(`connection`)??``).split(`,`))e.trim()&&t.delete(e.trim());for(let e of[`content-length`,`content-encoding`,`transfer-encoding`,`connection`,`keep-alive`,`trailer`,`upgrade`,`proxy-authenticate`,`proxy-authorization`])t.delete(e);return t}function o(e,t){if(e===void 0)return null;if(typeof e==`string`||e instanceof Blob||e instanceof ReadableStream||e instanceof ArrayBuffer)return e;if(ArrayBuffer.isView(e)){let t=new Uint8Array(e.byteLength);return t.set(new Uint8Array(e.buffer,e.byteOffset,e.byteLength)),t}if(e instanceof URLSearchParams||e instanceof FormData)return e;if(typeof e==`object`&&e&&`pipe`in e)throw TypeError(`Supply mapBody for a Node stream`);return t.has(`content-type`)||t.set(`content-type`,`application/json`),JSON.stringify(e)}export{t as formatEpochMilliseconds,e as formatOAuthIdentity,o as formatResponseBody,a as formatResponseHeaders,n as formatRpcFailure,r as normalizeAccelerator,i as shortcutIdentity};
+//# sourceMappingURL=formatter.js.map

package/dist/utils/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","names":["formatOAuthIdentity","data","formatEpochMilliseconds","value","formatRpcFailure","label","status","normalizeAccelerator","parts","part","key","order","names","shortcutIdentity","accelerator","isMac","formatResponseHeaders","headers","name","response","item","formatResponseBody","bytes"],"sources":["../../src/utils/formatter.ts"],"sourcesContent":["import type {\n  AuthIdentity,\n  DesktopRpcResponse,\n  OAuthIdentityClaims,\n} from \"@/utils/interface\";\nimport type { AxiosResponse } from \"axios\";\n\n/** Call only after provider identity validation. Never project authorization roles. */\nexport function formatOAuthIdentity(data: OAuthIdentityClaims): AuthIdentity {\n  return {\n    subject: data.sub,\n    name: data.name,\n    email: data.email,\n    emailVerified: data.email_verified,\n    username: data.preferred_username,\n    image: data.picture,\n  };\n}\n\nexport function formatEpochMilliseconds(value: Date | string | number): number {\n  return value instanceof Date\n    ? value.getTime()\n    : typeof value === \"string\"\n      ? Date.parse(value)\n      : value;\n}\n\nexport function formatRpcFailure(\n  status: number,\n  message: string,\n  code: number,\n  label: string,\n): DesktopRpcResponse {\n  return {\n    status,\n    body: JSON.stringify({\n      error: { message, code, data: { code: label, httpStatus: status } },\n    }),\n  };\n}\n\nexport function normalizeAccelerator(value: string): string {\n  if (!value.trim()) return \"\";\n  const parts = value.split(\"+\").map((part) => part.trim());\n  const key = parts.pop()!.replace(/^Arrow/, \"\");\n  if (\n    !/^(?:[a-z0-9,./;[\\]\\\\-]|Tab|Space|Plus|Enter|Backspace|Delete|Escape|Up|Down|Left|Right|F(?:[1-9]|1[0-9]|2[0-4]))$/i.test(\n      key,\n    )\n  )\n    throw new Error(\"Choose a letter, number, function key or navigation key.\");\n  const order = [\"CmdOrCtrl\", \"Ctrl\", \"Alt\", \"Shift\", \"Super\"];\n  if (\n    parts.some((part) => !order.includes(part)) ||\n    new Set(parts).size !== parts.length ||\n    (!parts.some((part) =>\n      [\"CmdOrCtrl\", \"Ctrl\", \"Alt\", \"Super\"].includes(part),\n    ) &&\n      !/^F\\d+$/i.test(key))\n  )\n    throw new Error(\"Use Command/Control, Alt, or a function key.\");\n  const names = [\n    \"Tab\",\n    \"Space\",\n    \"Plus\",\n    \"Enter\",\n    \"Backspace\",\n    \"Delete\",\n    \"Escape\",\n    \"Up\",\n    \"Down\",\n    \"Left\",\n    \"Right\",\n  ];\n  return [\n    ...order.filter((part) => parts.includes(part)),\n    names.find((part) => part.toLowerCase() === key.toLowerCase()) ??\n      key.toUpperCase(),\n  ].join(\"+\");\n}\n\nexport function shortcutIdentity(accelerator: string, isMac: boolean): string {\n  return accelerator\n    .replace(\"CmdOrCtrl\", isMac ? \"Super\" : \"Ctrl\")\n    .split(\"+\")\n    .sort()\n    .join(\"+\");\n}\n\nexport function formatResponseHeaders(response: AxiosResponse<unknown>) {\n  const headers = new Headers();\n  for (const [name, value] of Object.entries(response.headers)) {\n    if (value === undefined || value === null || value === false) continue;\n    for (const item of Array.isArray(value) ? value : [value])\n      headers.append(name, String(item));\n  }\n  for (const name of (headers.get(\"connection\") ?? \"\").split(\",\")) {\n    if (name.trim()) headers.delete(name.trim());\n  }\n  // Axios may have decompressed or reserialized the payload. These wire headers\n  // would otherwise make the downstream browser decode/count it a second time.\n  for (const name of [\n    \"content-length\",\n    \"content-encoding\",\n    \"transfer-encoding\",\n    \"connection\",\n    \"keep-alive\",\n    \"trailer\",\n    \"upgrade\",\n    \"proxy-authenticate\",\n    \"proxy-authorization\",\n  ])\n    headers.delete(name);\n  return headers;\n}\n\nexport function formatResponseBody(\n  data: unknown,\n  headers: Headers,\n): BodyInit | null {\n  if (data === undefined) return null;\n  if (\n    typeof data === \"string\" ||\n    data instanceof Blob ||\n    data instanceof ReadableStream\n  )\n    return data;\n  if (data instanceof ArrayBuffer) return data;\n  if (ArrayBuffer.isView(data)) {\n    const bytes = new Uint8Array(data.byteLength);\n    bytes.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));\n    return bytes;\n  }\n  if (data instanceof URLSearchParams || data instanceof FormData) return data;\n  if (typeof data === \"object\" && data !== null && \"pipe\" in data)\n    throw new TypeError(\"Supply mapBody for a Node stream\");\n  if (!headers.has(\"content-type\"))\n    headers.set(\"content-type\", \"application/json\");\n  return JSON.stringify(data);\n}\n"],"mappings":"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"}

package/dist/utils/interface.d.cts

@@ -0,0 +1,2 @@
+import { A as LogoutVerifierOptions, B as SupabaseAnyClient, C as DesktopRpcRequest, D as IdentityCacheInput, E as FetcherOptions, F as ResourceAuthOptions, H as UploadUtils, I as SessionGrantGuardOptions, L as Shortcut, M as OAuthIdentityValidatorOptions, N as ProofStorage, O as IdentityCacheOptions, P as RealtimeUtils, R as ShortcutDefinition, S as DesktopRpcPolicy, T as DesktopRpcTransportOptions, U as VerifiedLogout, V as UploadInput, W as WebResponseOptions, _ as CallerToastOptions, a as AuthIdentity, b as DefaultSchema, c as AuthRetryOptions, d as AuthSessionBinding, f as CallerErrorOptions, g as CallerResponseHandler, h as CallerRequestOptions, i as AuthFreshnessInput, j as OAuthIdentityClaims, k as LogoutStorage, l as AuthRevocation, m as CallerOptions, n as AuthErrorCode, o as AuthPolicy, p as CallerMethodOptions, r as AuthFreshness, s as AuthRetryInput, t as AuthCookieInput, u as AuthRevocationIdentity, v as CommonCookieMethods, w as DesktopRpcResponse, x as DesktopRpcHandlerOptions, y as DatabaseSchema, z as ShortcutPolicy } from "../interface-BR9QNgXO.cjs";
+export { AuthCookieInput, AuthErrorCode, AuthFreshness, AuthFreshnessInput, AuthIdentity, AuthPolicy, AuthRetryInput, AuthRetryOptions, AuthRevocation, AuthRevocationIdentity, AuthSessionBinding, CallerErrorOptions, CallerMethodOptions, CallerOptions, CallerRequestOptions, CallerResponseHandler, CallerToastOptions, CommonCookieMethods, DatabaseSchema, DefaultSchema, DesktopRpcHandlerOptions, DesktopRpcPolicy, DesktopRpcRequest, DesktopRpcResponse, DesktopRpcTransportOptions, FetcherOptions, IdentityCacheInput, IdentityCacheOptions, LogoutStorage, LogoutVerifierOptions, OAuthIdentityClaims, OAuthIdentityValidatorOptions, ProofStorage, RealtimeUtils, ResourceAuthOptions, SessionGrantGuardOptions, Shortcut, ShortcutDefinition, ShortcutPolicy, SupabaseAnyClient, UploadInput, UploadUtils, VerifiedLogout, WebResponseOptions };

package/dist/utils/interface.d.ts

@@ -0,0 +1,2 @@
+import { A as LogoutVerifierOptions, B as SupabaseAnyClient, C as DesktopRpcRequest, D as IdentityCacheInput, E as FetcherOptions, F as ResourceAuthOptions, H as UploadUtils, I as SessionGrantGuardOptions, L as Shortcut, M as OAuthIdentityValidatorOptions, N as ProofStorage, O as IdentityCacheOptions, P as RealtimeUtils, R as ShortcutDefinition, S as DesktopRpcPolicy, T as DesktopRpcTransportOptions, U as VerifiedLogout, V as UploadInput, W as WebResponseOptions, _ as CallerToastOptions, a as AuthIdentity, b as DefaultSchema, c as AuthRetryOptions, d as AuthSessionBinding, f as CallerErrorOptions, g as CallerResponseHandler, h as CallerRequestOptions, i as AuthFreshnessInput, j as OAuthIdentityClaims, k as LogoutStorage, l as AuthRevocation, m as CallerOptions, n as AuthErrorCode, o as AuthPolicy, p as CallerMethodOptions, r as AuthFreshness, s as AuthRetryInput, t as AuthCookieInput, u as AuthRevocationIdentity, v as CommonCookieMethods, w as DesktopRpcResponse, x as DesktopRpcHandlerOptions, y as DatabaseSchema, z as ShortcutPolicy } from "../interface-ii8DV63k.js";
+export { AuthCookieInput, AuthErrorCode, AuthFreshness, AuthFreshnessInput, AuthIdentity, AuthPolicy, AuthRetryInput, AuthRetryOptions, AuthRevocation, AuthRevocationIdentity, AuthSessionBinding, CallerErrorOptions, CallerMethodOptions, CallerOptions, CallerRequestOptions, CallerResponseHandler, CallerToastOptions, CommonCookieMethods, DatabaseSchema, DefaultSchema, DesktopRpcHandlerOptions, DesktopRpcPolicy, DesktopRpcRequest, DesktopRpcResponse, DesktopRpcTransportOptions, FetcherOptions, IdentityCacheInput, IdentityCacheOptions, LogoutStorage, LogoutVerifierOptions, OAuthIdentityClaims, OAuthIdentityValidatorOptions, ProofStorage, RealtimeUtils, ResourceAuthOptions, SessionGrantGuardOptions, Shortcut, ShortcutDefinition, ShortcutPolicy, SupabaseAnyClient, UploadInput, UploadUtils, VerifiedLogout, WebResponseOptions };

package/dist/utils/interface.js

@@ -0,0 +1 @@
+export{};

package/docs/auth.md

@@ -0,0 +1,183 @@
+# Native Better Auth integration
+
+Targets the installed Better Auth 1.7 SDK. Applications own `betterAuth({...})`,
+provider configuration, keys, trusted origins, database schemas/adapters,
+business permissions, cookies and routing. This package never reads env or
+connects to a database.
+
+SSO uses the official OAuth Provider; relying-party web apps use Generic OAuth
+with native account/session/verification storage. Electron uses the official
+Electron SDK with its app backend. Do not create another OAuth/session engine
+inside Structure or use an ID token as a service access token.
+
+## App-owned SDK and required peer
+
+`better-auth` is a **required peer dependency** (`^1.7`), not a runtime
+dependency installed and re-exported by Structure. The package pins 1.7 in its
+development dependencies only for builds and integration tests.
+
+Every consuming application must declare its own direct `better-auth`
+dependency, including Electron main and both runtimes of a split client/server
+application. A package manager may auto-install peers, so the peer declaration
+does not by itself enforce a direct dependency in the application's manifest.
+
+```sh
+bun add better-auth@1.7
+```
+
+Import native APIs directly:
+
+```ts
+import { betterAuth } from "better-auth";
+import { createAuthClient } from "better-auth/react";
+import { genericOAuth } from "better-auth/plugins/generic-oauth";
+import { requestToResourceInput, verifyAccessTokenRequest } from "better-auth/oauth2";
+```
+
+The `cores/auth` and `cores/auth/*` namespaces are retired and explicitly
+blocked by the export map. There are no compatibility re-exports. Native
+adapters, cookies, integrations and plugins must use their official package
+paths (for example `better-auth/adapters/drizzle`, `better-auth/cookies` and
+`better-auth/next-js`).
+
+Install optional features only in the app that uses them: OAuth Provider,
+enterprise SSO, Infra, SCIM, Stripe or Electron use their owning
+`@better-auth/*` package directly. Structure no longer depends on any of
+those feature packages. This is a breaking export change; publish a new
+breaking release/tag and update consumers deliberately.
+
+SDK clients use `signIn.social({ provider: configuredProviderId })` in 1.7;
+Generic OAuth does not need an invented `genericOAuthClient` plugin.
+`nextCookies` is server integration, not a renderer/client export.
+
+## Modules retained because current apps use them
+
+- `modules/auth/client`: `createAuthRetry`, `waitForAuthOperation`,
+  `AuthError`, configurable freshness/policy helpers. SDK owns session renewal;
+  retry only coalesces app-provided refresh/read callbacks, retries once after
+  401, and fences late refresh results after reset/dispose.
+- `modules/auth/server`: origin/return-path checks, SHA-256 fingerprints,
+  `createResourceAuth`, `createProofReplayStore`, `createLogoutVerifier`
+  and policy. API verification delegates to official
+  `verifyAccessTokenRequest`; persistent proof/revocation and local permissions
+  remain app-owned adapters.
+- Signed back-channel logout is still used by the apps. Signature, issuer,
+  audience, typ, expiry, event and replay checks cannot be removed just because
+  app sessions are now native.
+
+## New reusable helpers
+
+### Identity cache
+
+`createIdentityCache<Value>({ load, key?, maxAgeMs?, capacity?, maxPending?, now? })`
+extracts the repeated UserInfo coalescing/cache logic. Default TTL is 120 seconds,
+with 512 entries/pending operations; applications may override both.
+
+```ts
+import { createIdentityCache } from "@gorth/structure/modules/auth/server";
+
+const profiles = createIdentityCache({
+  load: loadValidatedActiveProfile,
+  maxAgeMs: applicationIdentityMaxAgeMs,
+});
+const profile = await profiles.get(accessToken, { fresh: sensitive, signal });
+await profiles.forget(accessToken); // invalidate when revoking this grant
+profiles.clear(); // invalidate this factory on teardown/global invalidation
+```
+
+The loader owns endpoint allowlisting, timeout, schema/status validation and
+safe rejection classification. Return immutable identity data. The default key
+is a SHA-256 fingerprint; raw credentials are not Map keys. Do not pass a raw
+token-returning custom `key` callback. A transient failure never returns expired
+identity data. Fresh calls bypass the cache and coalesce a currently running
+check. TTL starts before networking; already-stale results are not cached.
+Cancellation aborts only the waiter, not other callers' shared check.
+Invalidation fences older responses, including pending key derivation on clear.
+
+This is an **identity-only process-local cache**, not an authorization or
+distributed session/refresh/replay store. Every protected operation still checks
+token expiry/audience/scopes, durable revocation and local permissions. Sensitive
+operations can force an online check. Cache contents contain no tokens.
+
+### Native identity validator
+
+`createOAuthIdentityValidator({ providerId, subject, allowed? })` supplies
+`user.validateUserInfo`. The caller selects its additional user subject field;
+the helper accepts only that provider's SDK OAuth lifecycle with a matching
+non-empty `profile.sub`. Optional `allowed(profile)` implements app-owned
+identity status policy. Errors are safe identifiers, not provider payloads.
+
+It does not verify/decode JWTs or create users. SDK verification must be enabled
+in app provider configuration. Mutable email/username/SSO roles are never used
+to link identities or elevate local roles. Profile mapping, defaults and schema
+remain app-owned.
+
+### Session grant guard
+
+`createSessionGrantGuard({ read, assertAllowed, now? }).run(operation, signal?)`
+surrounds a native SDK credential-access operation, for example
+`auth.api.getAccessToken`. `read` returns an authoritative existing native
+session binding (`id, userId, subject, sid?, expiresAt`); `assertAllowed` checks
+durable revocation and local permissions.
+
+The guard checks before/after the operation and rejects missing, expired,
+revoked, cancelled or changed session/account bindings. It adds no session
+storage, token refresh, encryption or cookie format. Use it **before** sending
+the next upstream proxy request. It cannot undo a side effect or a request
+already dispatched, and does not revoke provider tokens itself. Multi-instance
+race prevention still needs the app's durable session/revocation fences.
+SDK handles token rotation; app handles grant revocation on local sign-out.
+
+### Revocation matching
+
+`matchesAuthRevocation(marker, identity, now?)` is a pure predicate for
+already-validated receipts. Both `sid` and subject must match when supplied;
+a subject-only event covers sessions issued through the end of that JWT issuance
+second, not future independent logins. All timestamps are epoch milliseconds.
+Expired markers do not match. Signature verification, durable receipt uniqueness,
+atomic session invalidation and retention remain with existing verifier/adapters.
+
+## Breaking legacy removal
+
+Removed runtime modules: custom OAuth/PKCE engine, custom session store/refresh
+engine, discovery/JWKS snapshot cache, session-bound transport, BFF HMAC,
+endpoint/schema helpers used only by those engines, purpose-bound JWE cipher,
+custom UI auth store/session adapter and loopback desktop login orchestration.
+Their dependent types, formatters, exports and package-only obsolete tests are
+removed too. Do not create fallback shims.
+
+Use native Generic OAuth, getSession/useSession/signOut/getAccessToken and
+`@better-auth/electron` instead. Do not migrate old ciphertext into native
+storage without an app-owned explicit migration.
+
+Active runtime imports in the ten apps and SSO were inspected and retained.
+Some **legacy consumer tests**, however, still exercise removed APIs:
+
+- Chat `tests/auth.test.ts`: custom OAuth/session contracts.
+- Browser and Launcher `tests/vitest/auth-timeout.test.ts`: `createDesktopLogin`.
+
+These must be replaced with native SDK tests before their next package update;
+they cannot continue to import intentionally deleted APIs. Archived `pkg`
+sources/docs can also mention them. No app, installed package, DB or SSO
+registration was modified in this package-only change.
+
+Publish as a **major release** because exports were intentionally removed.
+Version/tag/publication remains owner-controlled; current package version was
+not silently bumped. Publish and refresh consumer lockfiles before adopting new
+helpers. Other infrastructure modules (HTTP, desktop RPC/shortcuts, Supabase)
+are preserved rather than assuming auth migration makes them obsolete.
+
+## Verification
+
+`pnpm verify` checks types, runtime tests, ESM/CJS build and public exports.
+Tests cover SDK-native social login/account-selection/PKCE using an isolated
+memory adapter, identity cache races, freshness, logout, grants, audience/scopes,
+DPoP, browser-safe helper graphs, HTTP and desktop infrastructure.
+Fixtures are not production adapters or a live browser/cloud end-to-end test.
+
+References:
+
+- [Generic OAuth](https://better-auth.com/docs/plugins/generic-oauth)
+- [Session management](https://better-auth.com/docs/concepts/session-management)
+- [OAuth Provider](https://better-auth.com/docs/plugins/oauth-provider)
+- [Electron integration](https://better-auth.com/docs/integrations/electron)

package/docs/modules.md

@@ -0,0 +1,36 @@
+# Shared modules
+
+See [auth.md](auth.md) for SDK boundaries and breaking legacy removals.
+
+| Module                     | Responsibility                                                                                                                                |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modules/auth/client`      | Framework-independent request retry coordination and freshness decisions                                                                      |
+| `modules/auth/server`      | Identity cache/validator, native-session grant guard, revocation predicate, origin checks, native SDK resource verification and signed logout |
+| `modules/http`             | Injected Axios fetcher/caller, validation, safe errors, Web Response conversion                                                               |
+| `modules/desktop`          | Framework-free RPC packets and shortcut validation; not an auth engine                                                                        |
+| `modules/common`           | Supabase admin/client/realtime/upload helpers                                                                                                 |
+| `modules/supabase/next`    | Supabase SSR integration                                                                                                                      |
+| `modules/supabase/express` | Supabase server/client integration                                                                                                            |
+
+All configuration, credentials, adapters, callbacks, runtime platform objects
+and service destinations are supplied by the owning app. No module reads env,
+connects to DB on import, creates a configured Better Auth instance, opens a
+listener, or imports UI. Reusable contracts live in `src/utils/interface.ts`;
+pure formatting lives in `src/utils/formatter.ts`. Internal module imports use
+`@/` and async logic uses async/await with try/catch/finally.
+
+HTTP callers retain injected runtime adapters (including desktop XHR) and do
+not change QUIC/network settings. Caller mutations must opt into unsafe retries;
+auth endpoints do not retry implicitly. Web Response conversion preserves
+individual Set-Cookie, status and Location headers, and removes stale wire
+encoding/length/hop-by-hop headers. Custom error mapping/notifications are app
+callbacks, not UI package dependencies.
+
+Desktop RPC still requires app-owned IPC sender/frame validation and trusted
+preload transport. Shortcut policies/registration/persistence stay in the app.
+Supabase credentials/RLS/ownership remain app responsibilities.
+
+Use `pnpm verify` before releasing. The app-owned Better Auth SDK peer and direct
+import requirements are listed in auth.md. GitHub distribution remains private-to-npm;
+pin consumers to a tested release commit/tag. No app dependency or DB/cloud state
+is changed by building this package.

package/package.json

@@ -0,0 +1,189 @@
+{
+  "name": "@gorth-io/structure",
+  "version": "0.0.0-alpha.5",
+  "description": "",
+  "type": "module",
+  "author": "Gorthenburg",
+  "license": "GORTH",
+  "private": false,
+  "keywords": [
+    "gorth",
+    "supabase",
+    "ably",
+    "postgres",
+    "graphql",
+    "better-auth",
+    "client",
+    "server",
+    "desktop"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gorth-io/base-structure.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs/auth.md",
+    "docs/modules.md"
+  ],
+  "engines": {
+    "node": "24.x"
+  },
+  "packageManager": "bun@1.4.4",
+  "exports": {
+    "./utils/*": {
+      "types": "./dist/utils/*.d.ts",
+      "import": "./dist/utils/*.js",
+      "require": "./dist/utils/*.cjs"
+    },
+    "./modules/http": {
+      "types": "./dist/modules/http/index.d.ts",
+      "import": "./dist/modules/http/index.js",
+      "require": "./dist/modules/http/index.cjs"
+    },
+    "./modules/desktop": {
+      "types": "./dist/modules/desktop/index.d.ts",
+      "import": "./dist/modules/desktop/index.js",
+      "require": "./dist/modules/desktop/index.cjs"
+    },
+    "./modules/auth/client": {
+      "types": "./dist/modules/auth/client/index.d.ts",
+      "import": "./dist/modules/auth/client/index.js",
+      "require": "./dist/modules/auth/client/index.cjs"
+    },
+    "./modules/auth/server": {
+      "types": "./dist/modules/auth/server/index.d.ts",
+      "import": "./dist/modules/auth/server/index.js",
+      "require": "./dist/modules/auth/server/index.cjs"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./lib/*": {
+      "types": "./dist/lib/*.d.ts",
+      "import": "./dist/lib/*.js",
+      "require": "./dist/lib/*.cjs"
+    },
+    "./modules/*": {
+      "types": "./dist/modules/*.d.ts",
+      "import": "./dist/modules/*.js",
+      "require": "./dist/modules/*.cjs"
+    },
+    "./modules/*/*": {
+      "types": "./dist/modules/*/*.d.ts",
+      "import": "./dist/modules/*/*.js",
+      "require": "./dist/modules/*/*.cjs"
+    },
+    "./modules/*/*/*": {
+      "types": "./dist/modules/*/*/*.d.ts",
+      "import": "./dist/modules/*/*/*.js",
+      "require": "./dist/modules/*/*/*.cjs"
+    },
+    "./cores/*": {
+      "types": "./dist/cores/*.d.ts",
+      "import": "./dist/cores/*.js",
+      "require": "./dist/cores/*.cjs"
+    },
+    "./cores/*/*": {
+      "types": "./dist/cores/*/*.d.ts",
+      "import": "./dist/cores/*/*.js",
+      "require": "./dist/cores/*/*.cjs"
+    },
+    "./cores/*/*/*": {
+      "types": "./dist/cores/*/*/*.d.ts",
+      "import": "./dist/cores/*/*/*.js",
+      "require": "./dist/cores/*/*/*.cjs"
+    },
+    "./cores/auth": null,
+    "./cores/auth/*": null
+  },
+  "typesVersions": {
+    "*": {
+      "utils/*": [
+        "dist/utils/*.d.ts"
+      ],
+      "modules/http": [
+        "dist/modules/http/index.d.ts"
+      ],
+      "modules/desktop": [
+        "dist/modules/desktop/index.d.ts"
+      ],
+      "modules/auth/client": [
+        "dist/modules/auth/client/index.d.ts"
+      ],
+      "modules/auth/server": [
+        "dist/modules/auth/server/index.d.ts"
+      ],
+      "cores/*": [
+        "dist/cores/*.d.ts"
+      ],
+      "cores/*/*": [
+        "dist/cores/*/*.d.ts"
+      ],
+      "cores/*/*/*": [
+        "dist/cores/*/*/*.d.ts"
+      ],
+      "common/*": [
+        "dist/common/*.d.ts"
+      ],
+      "*": [
+        "dist/index.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsdown --minify",
+    "prepack": "bun run build",
+    "verify": "bun verify",
+    "dev": "tsdown --format esm,cjs --dts --out-dir dist --watch",
+    "lint": "eslint",
+    "format": "prettier --write \"**/*.{ts,tsx}\"",
+    "typecheck": "tsc --noEmit",
+    "update": "bun update",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:types": "tsc --project tsconfig.test.json",
+    "test:exports": "node --test tests/auth-exports.test.mjs"
+  },
+  "dependencies": {
+    "@ably/ai-transport": "^0.11.0",
+    "@ably/chat": "^2.0.0",
+    "@ably/spaces": "^0.6.0",
+    "@supabase/postgrest-js": "^2.118.0",
+    "@supabase/server": "^1.9.2",
+    "@supabase/ssr": "^0.12.7",
+    "@supabase/supabase-js": "^2.118.0",
+    "ably": "^2.30.0",
+    "axios": "^1.21.0",
+    "graphql": "^16.14.2",
+    "graphql-request": "^7.4.0",
+    "graphql-tag": "^2.12.7",
+    "jose": "^6.2.15",
+    "pg": "^8.23.1",
+    "postgres": "^4.0.0",
+    "uuid": "^14.0.3",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/pg": "^8.23.1",
+    "better-auth": "1.7.15",
+    "eslint": "^9.39.5",
+    "prettier": "^3.9.10",
+    "tsdown": "^0.23.4",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.1.0"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.7.15"
+  }
+}