@gorth-io/structure 0.0.0-alpha.6 → 0.0.0-alpha.8

package/dist/modules/http/failure.d.ts

@@ -0,0 +1,14 @@
+export interface ServiceFailure {
+  status: number;
+  code: string;
+  headers?: HeadersInit;
+  details?: Record<string, unknown>;
+}
+/** Only public codes belong here; never pass provider messages or credentials. */
+export declare class ServiceError extends Error {
+  readonly code: string;
+  readonly status: number;
+  constructor(code: string, status?: number);
+}
+export declare function serviceFailure(error: unknown): ServiceFailure | undefined;
+//# sourceMappingURL=failure.d.ts.map

package/dist/modules/http/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","names":[],"sources":["../../../src/modules/http/failure.ts"],"mappings":"A,iBAEiB;EACf;EACA;EACA,UAAU;EACV,UAAU;;;qBAIC,qBAAqB;WAEd;WACA;EADA,YAAA,cACA;;wBAcJ,eAAe,iBAAiB"}

package/dist/modules/http/failure.js

@@ -0,0 +1,2 @@
+import{ZodError as e}from"zod";var t=class extends Error{code;status;constructor(e,t=500){if(!/^[a-z][a-z0-9_]{0,127}$/.test(e)||!Number.isInteger(t)||t<400||t>599)throw TypeError(`Invalid service error contract`);super(e),this.code=e,this.status=t,this.name=`ServiceError`}};function n(n){if(n instanceof t)return{status:n.status,code:n.code};if(n instanceof e)return{status:400,code:`validation_error`,details:{issues:n.issues.map(e=>({code:e.code,path:e.path}))}}}export{t as ServiceError,n as serviceFailure};
+//# sourceMappingURL=failure.js.map

package/dist/modules/http/failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.js","names":["ServiceError","code","status","serviceFailure","error","ZodError","issue"],"sources":["../../../src/modules/http/failure.ts"],"sourcesContent":["import { ZodError } from \"zod\";\n\nexport interface ServiceFailure {\n  status: number;\n  code: string;\n  headers?: HeadersInit;\n  details?: Record<string, unknown>;\n}\n\n/** Only public codes belong here; never pass provider messages or credentials. */\nexport class ServiceError extends Error {\n  constructor(\n    public readonly code: string,\n    public readonly status = 500,\n  ) {\n    if (\n      !/^[a-z][a-z0-9_]{0,127}$/.test(code) ||\n      !Number.isInteger(status) ||\n      status < 400 ||\n      status > 599\n    )\n      throw new TypeError(\"Invalid service error contract\");\n    super(code);\n    this.name = \"ServiceError\";\n  }\n}\n\nexport function serviceFailure(error: unknown): ServiceFailure | undefined {\n  if (error instanceof ServiceError) return { status: error.status, code: error.code };\n  if (error instanceof ZodError)\n    return {\n      status: 400,\n      code: \"validation_error\",\n      details: {\n        // Do not return custom messages, inputs or schema internals by default.\n        issues: error.issues.map((issue) => ({ code: issue.code, path: issue.path })),\n      },\n    };\n}\n"],"mappings":"A,+BAUA,IAAaA,EAAb,cAAkC,KAAM,CAEpB,KACA,OAFlB,YACE,EACA,EAAyB,IACzB,CACA,GACE,CAAC,0BAA0B,KAAKC,CAAI,GACpC,CAAC,OAAO,UAAUC,CAAM,GACxBA,EAAS,KACTA,EAAS,IAET,MAAU,UAAU,gCAAgC,EACtD,MAAMD,CAAI,EAVM,KAAA,KAAAA,EACA,KAAA,OAAAC,EAUhB,KAAK,KAAO,cACd,CACF,EAEA,SAAgBC,EAAe,EAA4C,CACzE,GAAIC,aAAiBJ,EAAc,MAAO,CAAE,OAAQI,EAAM,OAAQ,KAAMA,EAAM,IAAK,EACnF,GAAIA,aAAiBC,EACnB,MAAO,CACL,OAAQ,IACR,KAAM,mBACN,QAAS,CAEP,OAAQD,EAAM,OAAO,IAAK,IAAW,CAAE,KAAME,EAAM,KAAM,KAAMA,EAAM,IAAK,EAAE,CAC9E,CACF,CACJ,C"}

package/dist/modules/http/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./caller.cjs"),t=require("./error.cjs"),n=require("./fetcher.cjs"),r=require("./response.cjs");exports.CallerError=t.CallerError,exports.createCaller=e.createCaller,exports.createFetcher=n.createFetcher,exports.normalizeCallerError=t.normalizeCallerError,exports.toWebResponse=r.toWebResponse;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./caller.cjs"),t=require("./error.cjs"),n=require("./fetcher.cjs"),r=require("./response.cjs"),i=require("./failure.cjs");exports.CallerError=t.CallerError,exports.ServiceError=i.ServiceError,exports.createCaller=e.createCaller,exports.createFetcher=n.createFetcher,exports.normalizeCallerError=t.normalizeCallerError,exports.serviceFailure=i.serviceFailure,exports.toWebResponse=r.toWebResponse;

package/dist/modules/http/index.d.cts

@@ -2,4 +2,5 @@ import { createCaller } from "./caller.cjs";
 import { E as FetcherOptions, G as CallerError, K as normalizeCallerError, W as WebResponseOptions, _ as CallerToastOptions, f as CallerErrorOptions, g as CallerResponseHandler, h as CallerRequestOptions, m as CallerOptions } from "../../interface-BR9QNgXO.cjs";
 import { createFetcher } from "./fetcher.cjs";
 import { toWebResponse } from "./response.cjs";
-export { CallerError, type CallerErrorOptions, type CallerOptions, type CallerRequestOptions, type CallerResponseHandler, type CallerToastOptions, type FetcherOptions, type WebResponseOptions, createCaller, createFetcher, normalizeCallerError, toWebResponse };
+import { ServiceError, ServiceFailure, serviceFailure } from "./failure.cjs";
+export { CallerError, type CallerErrorOptions, type CallerOptions, type CallerRequestOptions, type CallerResponseHandler, type CallerToastOptions, type FetcherOptions, ServiceError, type ServiceFailure, type WebResponseOptions, createCaller, createFetcher, normalizeCallerError, serviceFailure, toWebResponse };

package/dist/modules/http/index.d.ts

@@ -2,4 +2,5 @@ import { createCaller } from "./caller.js";
 import { E as FetcherOptions, G as CallerError, K as normalizeCallerError, W as WebResponseOptions, _ as CallerToastOptions, f as CallerErrorOptions, g as CallerResponseHandler, h as CallerRequestOptions, m as CallerOptions } from "../../interface-ii8DV63k.js";
 import { createFetcher } from "./fetcher.js";
 import { toWebResponse } from "./response.js";
-export { CallerError, type CallerErrorOptions, type CallerOptions, type CallerRequestOptions, type CallerResponseHandler, type CallerToastOptions, type FetcherOptions, type WebResponseOptions, createCaller, createFetcher, normalizeCallerError, toWebResponse };
+import { ServiceError, ServiceFailure, serviceFailure } from "./failure.js";
+export { CallerError, type CallerErrorOptions, type CallerOptions, type CallerRequestOptions, type CallerResponseHandler, type CallerToastOptions, type FetcherOptions, ServiceError, type ServiceFailure, type WebResponseOptions, createCaller, createFetcher, normalizeCallerError, serviceFailure, toWebResponse };

package/dist/modules/http/index.js

@@ -1 +1 @@
-import{createCaller as e}from"./caller.js";import{CallerError as t,normalizeCallerError as n}from"./error.js";import{createFetcher as r}from"./fetcher.js";import{toWebResponse as i}from"./response.js";export{t as CallerError,e as createCaller,r as createFetcher,n as normalizeCallerError,i as toWebResponse};
+import{createCaller as e}from"./caller.js";import{CallerError as t,normalizeCallerError as n}from"./error.js";import{createFetcher as r}from"./fetcher.js";import{toWebResponse as i}from"./response.js";import{ServiceError as a,serviceFailure as o}from"./failure.js";export{t as CallerError,a as ServiceError,e as createCaller,r as createFetcher,n as normalizeCallerError,o as serviceFailure,i as toWebResponse};

package/dist/utils/normalization.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t={}){try{if(typeof e!=`string`||e!==e.trim())throw Error();let n=new URL(e);if(n.username||n.password||n.hash||!t.allowQuery&&n.search||t.originOnly&&n.pathname!==`/`||n.protocol!==`https:`&&!(t.allowLoopbackHttp&&n.protocol===`http:`&&[`localhost`,`127.0.0.1`,`[::1]`].includes(n.hostname)))throw Error();return n}catch{throw TypeError(`Invalid HTTP endpoint`)}}function t(e){let t=typeof e==`string`&&/^\d+$/.test(e)?Number(e):e;if(typeof t!=`number`||!Number.isSafeInteger(t)||t<0)throw TypeError(`Invalid byte count`);return t}function n(e){let t=e instanceof Date?e.getTime():typeof e==`string`?Date.parse(e):e;if(!Number.isSafeInteger(t)||t<0)throw TypeError(`Invalid timestamp`);return t}exports.parseByteCount=t,exports.parseEpochMilliseconds=n,exports.parseHttpEndpoint=e;

package/dist/utils/normalization.d.cts

@@ -0,0 +1,10 @@
+export interface HttpEndpointOptions {
+  allowLoopbackHttp?: boolean;
+  allowQuery?: boolean;
+  originOnly?: boolean;
+}
+/** Syntax/transport validation only; callers still own destination allowlists. */
+export declare function parseHttpEndpoint(value: string, options?: HttpEndpointOptions): URL;
+export declare function parseByteCount(value: unknown): number;
+export declare function parseEpochMilliseconds(value: Date | string | number): number;
+//# sourceMappingURL=normalization.d.cts.map

package/dist/utils/normalization.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalization.d.cts","names":[],"sources":["../../src/utils/normalization.ts"],"mappings":"A,iBAAiB;EACf;EACA;EACA;;;wBAIc,kBACd,eACA,UAAS,sBACR;wBAwBa,eAAe;wBAQf,uBAAuB,OAAO"}

package/dist/utils/normalization.d.ts

@@ -0,0 +1,10 @@
+export interface HttpEndpointOptions {
+  allowLoopbackHttp?: boolean;
+  allowQuery?: boolean;
+  originOnly?: boolean;
+}
+/** Syntax/transport validation only; callers still own destination allowlists. */
+export declare function parseHttpEndpoint(value: string, options?: HttpEndpointOptions): URL;
+export declare function parseByteCount(value: unknown): number;
+export declare function parseEpochMilliseconds(value: Date | string | number): number;
+//# sourceMappingURL=normalization.d.ts.map

package/dist/utils/normalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalization.d.ts","names":[],"sources":["../../src/utils/normalization.ts"],"mappings":"A,iBAAiB;EACf;EACA;EACA;;;wBAIc,kBACd,eACA,UAAS,sBACR;wBAwBa,eAAe;wBAQf,uBAAuB,OAAO"}

package/dist/utils/normalization.js

@@ -0,0 +1,2 @@
+function e(e,t={}){try{if(typeof e!=`string`||e!==e.trim())throw Error();let n=new URL(e);if(n.username||n.password||n.hash||!t.allowQuery&&n.search||t.originOnly&&n.pathname!==`/`||n.protocol!==`https:`&&!(t.allowLoopbackHttp&&n.protocol===`http:`&&[`localhost`,`127.0.0.1`,`[::1]`].includes(n.hostname)))throw Error();return n}catch{throw TypeError(`Invalid HTTP endpoint`)}}function t(e){let t=typeof e==`string`&&/^\d+$/.test(e)?Number(e):e;if(typeof t!=`number`||!Number.isSafeInteger(t)||t<0)throw TypeError(`Invalid byte count`);return t}function n(e){let t=e instanceof Date?e.getTime():typeof e==`string`?Date.parse(e):e;if(!Number.isSafeInteger(t)||t<0)throw TypeError(`Invalid timestamp`);return t}export{t as parseByteCount,n as parseEpochMilliseconds,e as parseHttpEndpoint};
+//# sourceMappingURL=normalization.js.map

package/dist/utils/normalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalization.js","names":["parseHttpEndpoint","value","url","options","parseByteCount","number","parseEpochMilliseconds","result"],"sources":["../../src/utils/normalization.ts"],"sourcesContent":["export interface HttpEndpointOptions {\n  allowLoopbackHttp?: boolean;\n  allowQuery?: boolean;\n  originOnly?: boolean;\n}\n\n/** Syntax/transport validation only; callers still own destination allowlists. */\nexport function parseHttpEndpoint(\n  value: string,\n  options: HttpEndpointOptions = {},\n): URL {\n  try {\n    if (typeof value !== \"string\" || value !== value.trim()) throw new Error();\n    const url = new URL(value);\n    if (\n      url.username ||\n      url.password ||\n      url.hash ||\n      (!options.allowQuery && url.search) ||\n      (options.originOnly && url.pathname !== \"/\") ||\n      (url.protocol !== \"https:\" &&\n        !(\n          options.allowLoopbackHttp &&\n          url.protocol === \"http:\" &&\n          [\"localhost\", \"127.0.0.1\", \"[::1]\"].includes(url.hostname)\n        ))\n    )\n      throw new Error();\n    return url;\n  } catch {\n    throw new TypeError(\"Invalid HTTP endpoint\");\n  }\n}\n\nexport function parseByteCount(value: unknown): number {\n  const number =\n    typeof value === \"string\" && /^\\d+$/.test(value) ? Number(value) : value;\n  if (typeof number !== \"number\" || !Number.isSafeInteger(number) || number < 0)\n    throw new TypeError(\"Invalid byte count\");\n  return number;\n}\n\nexport function parseEpochMilliseconds(value: Date | string | number): number {\n  const result =\n    value instanceof Date\n      ? value.getTime()\n      : typeof value === \"string\"\n        ? Date.parse(value)\n        : value;\n  if (!Number.isSafeInteger(result) || result < 0)\n    throw new TypeError(\"Invalid timestamp\");\n  return result;\n}\n"],"mappings":"AAOA,SAAgBA,EACd,EACA,EAA+B,CAAC,EAC3B,CACL,GAAI,CACF,GAAI,OAAOC,GAAU,UAAYA,IAAUA,EAAM,KAAK,EAAG,MAAU,MAAM,EACzE,IAAMC,EAAM,IAAI,IAAID,CAAK,EACzB,GACEC,EAAI,UACJA,EAAI,UACJA,EAAI,MACH,CAACC,EAAQ,YAAcD,EAAI,QAC3BC,EAAQ,YAAcD,EAAI,WAAa,KACvCA,EAAI,WAAa,UAChB,EACEC,EAAQ,mBACRD,EAAI,WAAa,SACjB,CAAC,YAAa,YAAa,OAAO,CAAC,CAAC,SAASA,EAAI,QAAQ,GAG7D,MAAU,MAAM,EAClB,OAAOA,CACT,MAAQ,CACN,MAAU,UAAU,uBAAuB,CAC7C,CACF,CAEA,SAAgBE,EAAe,EAAwB,CACrD,IAAMC,EACJ,OAAOJ,GAAU,UAAY,QAAQ,KAAKA,CAAK,EAAI,OAAOA,CAAK,EAAIA,EACrE,GAAI,OAAOI,GAAW,UAAY,CAAC,OAAO,cAAcA,CAAM,GAAKA,EAAS,EAC1E,MAAU,UAAU,oBAAoB,EAC1C,OAAOA,CACT,CAEA,SAAgBC,EAAuB,EAAuC,CAC5E,IAAMC,EACJN,aAAiB,KACbA,EAAM,QAAQ,EACd,OAAOA,GAAU,SACf,KAAK,MAAMA,CAAK,EAChBA,EACR,GAAI,CAAC,OAAO,cAAcM,CAAM,GAAKA,EAAS,EAC5C,MAAU,UAAU,mBAAmB,EACzC,OAAOA,CACT,C"}

package/docs/modules.md

@@ -30,7 +30,71 @@ 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
+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

@@ -1,7 +1,7 @@
 {
   "name": "@gorth-io/structure",
-  "version": "0.0.0-alpha.6",
-  "description": "",
+  "version": "0.0.0-alpha.8",
+  "description": "TypeScript infrastructure for HTTP clients, authentication coordination, Supabase, and database integrations in the gorth-io ecosystem.",
   "type": "module",
   "author": "Gorthenburg",
   "license": "GORTH",
@@ -23,6 +23,7 @@
   },
   "publishConfig": {
     "access": "public",
+    "tag": "alpha",
     "registry": "https://registry.npmjs.org"
   },
   "main": "./dist/index.cjs",
@@ -38,6 +39,11 @@
   },
   "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",
@@ -108,6 +114,9 @@
   },
   "typesVersions": {
     "*": {
+      "modules/database": [
+        "dist/modules/database/index.d.ts"
+      ],
       "utils/*": [
         "dist/utils/*.d.ts"
       ],
@@ -144,7 +153,7 @@
     "build": "tsdown --minify",
     "prepack": "bun run build",
     "verify": "bun verify",
-    "dev": "tsdown --format esm,cjs --dts --out-dir dist --watch",
+    "dev": "tsdown --format esm,cjs --dts --out-dir dist --watch --no-clean",
     "lint": "eslint",
     "format": "prettier --write \"**/*.{ts,tsx}\"",
     "typecheck": "tsc --noEmit",
@@ -157,10 +166,10 @@
     "@ably/ai-transport": "^0.11.0",
     "@ably/chat": "^2.0.0",
     "@ably/spaces": "^0.6.0",
-    "@supabase/postgrest-js": "^2.118.0",
+    "@supabase/postgrest-js": "^2.119.0",
     "@supabase/server": "^1.9.2",
     "@supabase/ssr": "^0.12.7",
-    "@supabase/supabase-js": "^2.118.0",
+    "@supabase/supabase-js": "^2.119.0",
     "ably": "^2.30.0",
     "axios": "^1.21.0",
     "graphql": "^16.14.2",
@@ -175,7 +184,7 @@
   "devDependencies": {
     "@types/node": "^26.6.6",
     "@types/pg": "^8.23.1",
-    "better-auth": "1.7.16",
+    "better-auth": "1.7.17",
     "eslint": "^9.39.5",
     "prettier": "^3.9.10",
     "tsdown": "^0.23.5",
@@ -184,6 +193,6 @@
     "vitest": "^5.1.0"
   },
   "peerDependencies": {
-    "better-auth": "^1.7.16"
+    "better-auth": "^1.7.17"
   }
 }