@terrascale/sdk 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.0.2 — TS-650
+
+TerraBase version tokens are opaque: `tbv1-<32 hex>` and the coming `tbv2-…`
+format are both accepted (any 1-256 visible ASCII characters without quotes, so
+they stay safe in `If-Match`). Responses with new members no longer throw:
+`durability` passes through any label, and documents pass through any `state`,
+including a causal read's `"conflict"` with its `siblings` (the LWW winner stays
+in `document`). Conditional writes and error handling are unchanged.
+
 ## 0.0.1 — TS-498
 
 The package moves from the unscoped `terrascale` npm name, which the owner has

package/README.md

@@ -79,7 +79,9 @@ The C# producer owns these routes:
 Collection methods are `get`, `put`, `create`, `patch`, `delete`, `query`,
 `pages` and `items`. New document IDs are canonical UUIDs; `documentIdFor`
 generates a stable UUIDv5 from a natural key. Documents return
-`{ id, version, state: "value", document }`. Writes return the version and a
+`{ id, version, state: "value", document }`; a causal read can answer
+`state: "conflict"` with `siblings`, and unknown states pass through. Versions
+(`tbv1-…`, `tbv2-…`) are opaque tokens. Writes return the version and a
 decimal-string commit `offset`; preserve those opaque positions and use
 `ifMatch` or `ifNoneMatchAny` for conditional writes.
 
@@ -198,4 +200,4 @@ Hosted OAuth resource requests use one exact registered HTTPS `resource`. `oidc.
 
 `oauthClients` and `oauthResources` provide the producer's snake_case policy records and named management operations. Resource PATCH requires `expected_auth_epoch`; client PATCH accepts it. JSON epochs outside JavaScript's exact integer range are rejected. Client PATCH returns a bare client view unless `rotate_secret` is true, when it returns the client and its one-time secret. Resource create/PATCH always return the resource and nullable one-time introspection secret.
 
-Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary.
+Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary. Behind the Atlas proxy `apiBaseUrl` `https://auth.terrascale.tech`, ts-auth's issuer is regional, `https://<region>.auth.terrascale.tech/<slug>` (for example `https://gru.auth.terrascale.tech/<slug>`); configure that issuer, not the proxy host. Resource introspection then calls the issuer's regional host directly, because Atlas could rank another region, which is another issuer; `useReverseProxy` keeps it on the proxy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",

package/src/http.js

@@ -1,6 +1,9 @@
 import { resolveAccessToken, resolveTsAuthRuntimeConfig } from "./config.js";
 import { err, ok, sanitizeDiagnostic } from "./result.js";
-import { TsAuthEndpointDiscovery } from "./ts-auth-discovery.js";
+import {
+  regionalIssuerOrigin,
+  TsAuthEndpointDiscovery,
+} from "./ts-auth-discovery.js";
 import { parseDatabaseJson } from "./database-codec.js";
 /** @import { ResolvedTsAuthRuntimeConfig, TsAuthRuntimeConfig, FetchLike } from "./config.js" */
 /** @import { TerraScaleError, TerraScaleErrorCategory, TerraScaleResult, TerraScaleValidationIssue } from "./result.js" */
@@ -18,6 +21,7 @@ import { parseDatabaseJson } from "./database-codec.js";
  *   readonly formBody?: URLSearchParams | string | undefined;
  *   readonly userinfoAccessToken?: string | undefined;
  *   readonly resourceIntrospectionBasic?: string | undefined;
+ *   readonly issuer?: string | undefined; // Behind the Atlas proxy a regional issuer is called on its own host.
  *   readonly signal?: AbortSignal | undefined;
  * }} TsAuthRequest
  */
@@ -85,10 +89,17 @@ export class TsAuthHttp {
         options.body !== undefined
           ? JSON.stringify(options.body)
           : options.formBody?.toString();
-      const endpoints = await withCancellation(
-        this.#discovery?.endpoints(signal) ?? Promise.resolve(undefined),
-        signal,
-      );
+      const issuerOrigin =
+        this.#discovery === undefined || options.issuer === undefined
+          ? undefined
+          : regionalIssuerOrigin(options.issuer);
+      const endpoints =
+        issuerOrigin === undefined
+          ? await withCancellation(
+              this.#discovery?.endpoints(signal) ?? Promise.resolve(undefined),
+              signal,
+            )
+          : [issuerOrigin];
       let endpointIndex = 0;
       let attempt = 0;
       let refreshed = false;

package/src/ts-auth-discovery.js

@@ -3,6 +3,23 @@ const AUTH_DISCOVERY_URL =
 const MAX_ENDPOINTS = 20;
 const MAX_BYTES = 65_536;
 
+/**
+ * ts-auth issues from its regional host, https://<region>.auth.terrascale.tech.
+ * Behind the Atlas proxy that issuer's region is called directly: Atlas could
+ * rank another region, which is another issuer.
+ * @param {string} issuer
+ * @returns {string | undefined}
+ */
+export function regionalIssuerOrigin(issuer) {
+  const region =
+    /^https:\/\/([a-z0-9][a-z0-9-]{0,15})\.auth\.terrascale\.tech\//u.exec(
+      issuer,
+    )?.[1];
+  return region === undefined
+    ? undefined
+    : `https://${region}.auth.terrascale.tech`;
+}
+
 /** The public auth routing document, validated before any credentials are sent. */
 export class TsAuthEndpointDiscovery {
   /**

package/src/ts-auth.js

@@ -2358,6 +2358,7 @@ export class TsAuthOidcClient {
         routeName: "tsauth.oidc.resourceIntrospect",
         formBody: form,
         resourceIntrospectionBasic: basic,
+        issuer: expectedIssuer,
       }),
       /** @returns {value is TsAuthOidcResourceIntrospection} */
       (value) => {

package/src/v1/decode.js

@@ -3,10 +3,16 @@ import { parseU64, requireVersion } from "./ids.js";
 import { isJsonObject } from "./json.js";
 /** @import { JsonObject, JsonValue } from "./json.js" */
 
-/** @typedef {"local_durable"} V1Durability */
+/** Unknown future labels pass through. @typedef {"local_durable" | (string & {})} V1Durability */
 /**
- * C# single-writer documents always carry a value, never conflict siblings.
- * @typedef {{ readonly id: string; readonly version: string; readonly state: "value"; readonly document: JsonObject }} V1Document
+ * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
+ * Unknown future states pass through.
+ * @typedef {object} V1Document
+ * @property {string} id
+ * @property {string} version
+ * @property {"value" | "conflict" | (string & {})} state
+ * @property {JsonObject} document
+ * @property {readonly JsonValue[]} [siblings] Every live version, on a causal read with several.
  */
 
 /**
@@ -78,7 +84,7 @@ export function array(value, what) {
  * @returns {V1Durability}
  */
 export function durability(value) {
-  return value === "local_durable" ? value : malformed("durability");
+  return string(value, "durability");
 }
 
 /**
@@ -89,8 +95,10 @@ export function decodeDocument(value) {
   const raw = object(value, "document");
   const id = string(raw.id, "document id");
   const version = requireVersion(raw.version);
-  if (raw.state !== "value") return malformed("document state");
-  return Object.freeze({ id, version, state: "value", document: object(raw.document, "document body") });
+  const state = string(raw.state, "document state");
+  const document = object(raw.document, "document body");
+  if (raw.siblings === undefined) return Object.freeze({ id, version, state, document });
+  return Object.freeze({ id, version, state, document, siblings: Object.freeze(array(raw.siblings, "document siblings")) });
 }
 
 /**

package/src/v1/ids.js

@@ -1,7 +1,8 @@
 // Identifiers for the TerraBase v1 Documents API (api-v1.md).
 
 const namePattern = /^[a-z][a-z0-9_-]{0,62}$/u;
-const versionPattern = /^tbv1-[0-9a-f]{32}$/u;
+// Version tokens are opaque (tbv1-<32 hex>, tbv2-...): only RFC 9110 opaque-tag characters, safe to quote in If-Match.
+const versionPattern = /^[\x21\x23-\x7e]{1,256}$/u;
 const offsetPattern = /^(?:0|[1-9]\d{0,19})$/u;
 const maximumU64 = (1n << 64n) - 1n;
 
@@ -49,7 +50,7 @@ export function requireDocumentId(id) {
  */
 export function requireVersion(version) {
   if (typeof version !== "string" || !versionPattern.test(version))
-    throw new TypeError("TerraBase versions are tbv1- followed by 32 lowercase hex characters.");
+    throw new TypeError("TerraBase versions are opaque tokens of 1-256 visible ASCII characters without quotes.");
   return version;
 }
 

package/types/http.d.ts

@@ -39,6 +39,7 @@ export type TsAuthRequest<TBody> = {
     readonly formBody?: URLSearchParams | string | undefined;
     readonly userinfoAccessToken?: string | undefined;
     readonly resourceIntrospectionBasic?: string | undefined;
+    readonly issuer?: string | undefined;
     readonly signal?: AbortSignal | undefined;
 };
 import type { ResolvedTsAuthRuntimeConfig } from "./config.js";

package/types/ts-auth-discovery.d.ts

@@ -1,3 +1,11 @@
+/**
+ * ts-auth issues from its regional host, https://<region>.auth.terrascale.tech.
+ * Behind the Atlas proxy that issuer's region is called directly: Atlas could
+ * rank another region, which is another issuer.
+ * @param {string} issuer
+ * @returns {string | undefined}
+ */
+export function regionalIssuerOrigin(issuer: string): string | undefined;
 /** The public auth routing document, validated before any credentials are sent. */
 export class TsAuthEndpointDiscovery {
     /** @param {typeof globalThis.fetch} fetchHandler */

package/types/v1/decode.d.ts

@@ -1,8 +1,14 @@
 /** @import { JsonObject, JsonValue } from "./json.js" */
-/** @typedef {"local_durable"} V1Durability */
+/** Unknown future labels pass through. @typedef {"local_durable" | (string & {})} V1Durability */
 /**
- * C# single-writer documents always carry a value, never conflict siblings.
- * @typedef {{ readonly id: string; readonly version: string; readonly state: "value"; readonly document: JsonObject }} V1Document
+ * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
+ * Unknown future states pass through.
+ * @typedef {object} V1Document
+ * @property {string} id
+ * @property {string} version
+ * @property {"value" | "conflict" | (string & {})} state
+ * @property {JsonObject} document
+ * @property {readonly JsonValue[]} [siblings] Every live version, on a causal read with several.
  */
 /**
  * The result of a document write.
@@ -68,15 +74,23 @@ export function decodeWrite(response: {
     headers: Headers;
     value: JsonValue | undefined;
 }): V1WriteResult;
-export type V1Durability = "local_durable";
 /**
- * C# single-writer documents always carry a value, never conflict siblings.
+ * Unknown future labels pass through.
+ */
+export type V1Durability = "local_durable" | (string & {});
+/**
+ * `document` is the value, or the LWW winner when a causal read answers `"conflict"` with `siblings`.
+ * Unknown future states pass through.
  */
 export type V1Document = {
-    readonly id: string;
-    readonly version: string;
-    readonly state: "value";
-    readonly document: JsonObject;
+    id: string;
+    version: string;
+    state: "value" | "conflict" | (string & {});
+    document: JsonObject;
+    /**
+     * Every live version, on a causal read with several.
+     */
+    siblings?: readonly JsonValue[];
 };
 /**
  * The result of a document write.