@gorth-io/structure 0.0.0-alpha.10

package/docs/modules.md

@@ -0,0 +1,100 @@
+# 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 `bun run typecheck`, `bun run test`, `bun run test:types` and `bun run test:exports` 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.
+
+## Shared infrastructure extraction (M03–M10, M15–M20)
+
+These are library mechanisms, not an application migration. Use the public
+`@gorth-io/structure` subpaths after publishing/installing a new version.
+Better Auth remains an external host peer; `cores/auth/*` remains blocked.
+
+| Public entry | API | Host responsibilities |
+| --- | --- | --- |
+| `modules/auth/server` | `createBearerVerifier`, `authFailure`, claim/continuity assertions | Trusted issuer/JWKS/audience, scopes, client-to-app binding, revocation and local ACL |
+| `modules/auth/server` | `createOAuthProviderConfig`, `mapOAuthUserProfile` | Call native `genericOAuth`; create the auth instance, hooks, cookies, provider ID and app policy |
+| `modules/auth/server` | `createUserInfoCache`, `oauthUserInfoSchema` | Inject loader/parser/admission predicate; own endpoint, transport and DB synchronization |
+| `modules/auth/server` | `createAtomicProofStorage`, existing proof/logout/revocation helpers | Durable atomic expired-key replacement/insert-if-absent, SQL transactions, receipt persistence |
+| `modules/auth/server` | `createMachineTokenRequest`, `parseMachineToken` | Supply credentials, scopes/resources and trusted token endpoint; execute the grant via bounded transport |
+| `modules/http` | `ServiceError`, `serviceFailure` | Public error vocabulary; explicitly map other native/framework errors |
+| `modules/database` | `parseDatabasePoolOptions`, `createDatabasePoolFactory` | Read env; cache, close and observe pools; own schema/migrations |
+| `modules/database/postgres` | `createPostgresPool` | Node-only explicit factory call; no eager connection on import |
+| `modules/desktop` | `releaseVersion`, `isNewerRelease`, `parseRelease`, proxy schema/config | Artifact trust/signatures, download/install, OS state and credentials |
+| `modules/desktop` | `resolveDesktopRpcPolicy` | Forge/env/socket lifecycle, IPC origin/frame checks and renderer boundaries |
+| `utils/normalization` | `parseHttpEndpoint`, `parseByteCount`, `parseEpochMilliseconds` | Destination allowlists and application-specific defaults; display formatters remain separate |
+
+```ts
+import { genericOAuth } from "better-auth/plugins/generic-oauth";
+import { createOAuthProviderConfig } from "@gorth-io/structure/modules/auth/server";
+
+// All values/callbacks below come from the owning app's validated configuration.
+const config = createOAuthProviderConfig({
+  ...providerOptions,
+  scopes: requestedScopes,
+  resources: registeredResources,
+});
+const providerPlugin = genericOAuth({ config: [config] });
+```
+
+`createBearerVerifier` is JWT Bearer-only and rejects DPoP-bound grants. Use
+the existing `createResourceAuth` with durable proof/revocation stores for DPoP.
+Its `authorize` callback must still enforce the owning service's client/scope
+binding and local status. `authFailure` projects safe codes/challenges, not raw
+provider causes. `serviceFailure` omits validation input/custom messages.
+
+`createUserInfoCache` adds typed profile parsing, expected-subject checking and
+an injected admission predicate to the existing bounded/coalescing/fenced cache.
+`createSessionGrantGuard` re-reads the app binding around native SDK operations;
+`assertTokenContinuity` binds verified sub/sid to that local session. These helpers
+do not implement refresh, account linking, user persistence or app authorization.
+
+The replay adapter has no in-memory fallback. Its `reserve` callback must be
+atomic across all deployment instances; tests using a fake store do not prove
+production database atomicity. Rate-limit storage follows the same host-owned rule.
+
+`createAtomicDpopReplayStore({ reserve })` accepts the native SDK reservation
+directly. It preserves both `now` and `expiresAt` as Date values, so a durable SQL
+adapter keeps the verifier's clock and transaction boundary. Duplicate reservations
+return false; invalid input and storage failures fail closed. It does not verify
+proofs or replace the native Better Auth DPoP verifier.
+
+M16 implements data/protocol normalization only. No localized byte/date/name UI
+formatter was moved from Primitive or an app. M19 exposes existing RPC option
+validation; `.env.local` loading remains a host concern using the platform API.
+
+Verification: `bun run typecheck`, `bun run test:types`, `bun run test`,
+`bun run build`, then `bun run test:exports`. No install/publish/database command
+is part of these checks. The Ably Spaces facade now follows its installed SDK's
+named exports (`createSpacesClient`); that SDK no longer has a default export.

package/package.json

@@ -0,0 +1,198 @@
+{
+  "name": "@gorth-io/structure",
+  "version": "0.0.0-alpha.10",
+  "description": "TypeScript infrastructure for HTTP clients, authentication coordination, Supabase, and database integrations in the gorth-io ecosystem.",
+  "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",
+    "tag": "alpha",
+    "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": {
+    "./modules/database": {
+      "types": "./dist/modules/database/index.d.ts",
+      "import": "./dist/modules/database/index.js",
+      "require": "./dist/modules/database/index.cjs"
+    },
+    "./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": {
+    "*": {
+      "modules/database": [
+        "dist/modules/database/index.d.ts"
+      ],
+      "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 --no-clean",
+    "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.119.0",
+    "@supabase/server": "^1.9.2",
+    "@supabase/ssr": "^0.12.7",
+    "@supabase/supabase-js": "^2.119.0",
+    "ably": "^2.30.0",
+    "axios": "^1.21.1",
+    "graphql": "^16.14.2",
+    "graphql-request": "^7.4.0",
+    "graphql-tag": "^2.12.7",
+    "jose": "^6.2.17",
+    "pg": "^8.23.1",
+    "postgres": "^4.1.1",
+    "uuid": "^14.0.3",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/pg": "^8.23.1",
+    "better-auth": "1.7.21",
+    "eslint": "^9.39.5",
+    "prettier": "^3.10.0",
+    "tsdown": "^0.23.7",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.1.0"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.7.21"
+  }
+}