@onlyworlds/sdk 4.103.0 → 4.104.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,17 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.104.0] - 2026-10-29
9
+
10
+ ### Added
11
+
12
+ - **Sign in with OnlyWorlds from a native app** (RFC 8252). A tool registered as native lists a loopback return without a port (`http://127.0.0.1/<path>` or `http://[::1]/<path>`) or its own scheme (`obsidian://onlyworlds-signin`). `signInWithOnlyWorlds` now takes, beside an `https:` address, the loopback address with the port the app bound for this sign-in (`http://127.0.0.1:53682/onlyworlds-signin`, 1 to 65535, written plainly), which the server matches against the portless one, and a custom scheme exactly as registered (lower-case, not `http`, `https`, `javascript`, `data` or `file`, something after `://`). It refuses `localhost`, a loopback without its port, and on any form userinfo, a query, a fragment and a dot segment (and an `https:` address with an upper-case host or no path, which it took before), with a TypeError naming the forms it takes: the server would refuse each of them at authorize. Whether the tool is registered as native is the server's to check; the SDK does not read the client list. A native app opens the authorize URL in the system browser through `navigate`, and passes the address its loopback server or scheme handler received to `completeSignIn` as `url`.
13
+
14
+ ### Fixed
15
+
16
+ - **`completeSignIn` compares the return address exactly**: its scheme, its host with the port, and its path. It compared `URL.origin`, which is `"null"` for every scheme that is not special, so a page at `evil://onlyworlds-signin` would have matched a sign-in begun for `obsidian://onlyworlds-signin` (out of reach until now, since only `https:` could be begun). A trailing slash is still tolerated on `https:`, where a static host may answer `/callback` by sending the browser to `/callback/`; on a loopback or custom-scheme address it is not.
17
+ - **`completeSignIn` cleans the address bar only when it read the address from `location`.** With `url` given, the window's history is left alone: a native app's callback address is not the address of the window it runs in.
18
+
8
19
  ## [4.103.0] - 2026-10-29
9
20
 
10
21
  ### Changed
package/dist/index.d.ts CHANGED
@@ -3865,7 +3865,14 @@ interface OwSignInStorage {
3865
3865
  interface OwSignInBegin {
3866
3866
  /** The `client_id` keel's registry lists the tool under (`GET /api/v2/auth/clients`). */
3867
3867
  clientId: string;
3868
- /** The registered return address, the exact string, `https:` only; never built from `location.origin`. */
3868
+ /**
3869
+ * The registered return address, the exact string; never built from `location.origin`. A web tool's
3870
+ * is `https:`. A tool registered as a native app may also use a loopback address, registered without
3871
+ * a port (`http://127.0.0.1/<path>` or `http://[::1]/<path>`) and passed here with the port the app
3872
+ * bound for this sign-in (`http://127.0.0.1:53682/<path>`, 1 to 65535), or its own scheme, exactly as
3873
+ * registered (`obsidian://onlyworlds-signin`). `localhost`, a loopback without its port, userinfo, a
3874
+ * query and a fragment are refused.
3875
+ */
3869
3876
  redirectUri: string;
3870
3877
  /** Small JSON the tool wants back after the redirect (an open link, a pending join code). */
3871
3878
  resume?: unknown;
@@ -3882,7 +3889,11 @@ interface OwSignInBegun {
3882
3889
  interface OwSignInComplete {
3883
3890
  clientId: string;
3884
3891
  storage?: OwSignInStorage;
3885
- /** The callback page's address; defaults to `location.href`. */
3892
+ /**
3893
+ * The callback page's address; defaults to `location.href`, which is then cleaned of `code` and
3894
+ * `state`. A native app passes the address its loopback server or scheme handler received, and
3895
+ * the window's history is left alone.
3896
+ */
3886
3897
  url?: string;
3887
3898
  }
3888
3899
  /** What `completeSignIn` returns: the account token, shown only here, and what the tool parked. */
@@ -4702,15 +4713,20 @@ declare class OwV2Client {
4702
4713
  * Start Sign in with OnlyWorlds from a tool's page: mint `state` and a PKCE verifier, keep them
4703
4714
  * under `clientId` in `storage` (sessionStorage by default; in Node pass one), and send the
4704
4715
  * browser to `https://www.onlyworlds.com/signin/authorize` (or only return the URL with
4705
- * `navigate: false`). `redirectUri` is the registered return address as a string, `https:`
4706
- * only, never built from `location.origin`: a tool's registration is read at
4707
- * `GET /api/v2/auth/clients`. `resume` is small JSON handed back by `completeSignIn`. No request
4708
- * is sent; any client, keyless included.
4716
+ * `navigate: false`). `redirectUri` is the registered return address as a string, never built
4717
+ * from `location.origin`: a tool's registration is read at `GET /api/v2/auth/clients`. A web
4718
+ * tool's is `https:`; a tool registered as native may pass a loopback address with the port it
4719
+ * bound for this sign-in (`http://127.0.0.1:<port>/<path>` or `http://[::1]:<port>/<path>`,
4720
+ * registered without the port) or its own scheme as registered (`obsidian://onlyworlds-signin`),
4721
+ * and opens the URL in the system browser with `navigate`. `resume` is small JSON handed back by
4722
+ * `completeSignIn`. No request is sent; any client, keyless included.
4709
4723
  */
4710
4724
  signInWithOnlyWorlds(opts: OwSignInBegin): Promise<OwSignInBegun>;
4711
4725
  /**
4712
4726
  * Finish Sign in with OnlyWorlds on the callback page: check `state` against the record and the
4713
- * page against the registered address, take `code` and `state` out of the address bar, trade
4727
+ * page against the registered address (scheme, host with port, and path, each exactly), take
4728
+ * `code` and `state` out of the address bar (only when `url` is not given: a native app passes
4729
+ * the address its loopback server or scheme handler received), trade
4714
4730
  * the code once at `POST /auth/token` with the PKCE verifier and no credential, and return the
4715
4731
  * `ow_a_` token with the account and `resume`. The record is cleared on success and on refusal;
4716
4732
  * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
package/dist/index.js CHANGED
@@ -501,11 +501,63 @@ function randomToken(bytes) {
501
501
  function sitePage(baseUrl, path) {
502
502
  return `${new URL(baseUrl).origin}${path}`;
503
503
  }
504
+ var LOOPBACK_HOSTS = ["127.0.0.1", "[::1]"];
505
+ var REFUSED_SCHEMES = ["http", "https", "javascript", "data", "file"];
506
+ var SCHEME = /^[a-z][a-z0-9+.-]*$/;
507
+ var PORT = /^[1-9][0-9]{0,4}$/;
508
+ function pathProblem(path) {
509
+ const segments = path.split("/");
510
+ if (segments.includes(".") || segments.includes("..")) return "carries a dot segment";
511
+ return null;
512
+ }
513
+ function redirectProblem(uri) {
514
+ if (typeof uri !== "string" || uri === "") return "is not a string";
515
+ for (let i = 0; i < uri.length; i++) {
516
+ const c = uri.charCodeAt(i);
517
+ if (c < 33 || c > 126) return "carries whitespace or a character outside printable ASCII";
518
+ }
519
+ if (uri.includes("*")) return "carries a wildcard: a return address is exact";
520
+ if (uri.includes("#")) return "carries a fragment";
521
+ if (uri.includes("?")) return "carries a query: the code and state are the only query";
522
+ const sep = uri.indexOf("://");
523
+ if (sep < 0) return "is not <scheme>://<path>";
524
+ const scheme = uri.slice(0, sep);
525
+ const rest = uri.slice(sep + 3);
526
+ const slash = rest.indexOf("/");
527
+ const netloc = slash < 0 ? rest : rest.slice(0, slash);
528
+ const path = slash < 0 ? "" : rest.slice(slash);
529
+ if (scheme === "https") {
530
+ if (netloc.includes("@")) return "carries userinfo";
531
+ const host = netloc.split(":")[0];
532
+ if (host === "" || host.includes("[")) return "has no plain host";
533
+ if (host !== host.toLowerCase()) return "has an upper-case host";
534
+ if (path === "") return "has no path";
535
+ return pathProblem(path);
536
+ }
537
+ if (scheme === "http") {
538
+ if (netloc.includes("@")) return "carries userinfo";
539
+ if (netloc.split(":")[0].toLowerCase() === "localhost") return "names localhost: a loopback return is the literal 127.0.0.1 or [::1]";
540
+ if (LOOPBACK_HOSTS.includes(netloc)) return "names no port: a loopback return carries the port the app bound";
541
+ const host = LOOPBACK_HOSTS.find((h) => netloc.startsWith(h + ":"));
542
+ if (host === void 0) return "is http on a host that is not a loopback literal (127.0.0.1 or [::1])";
543
+ const port = netloc.slice(host.length + 1);
544
+ if (!PORT.test(port) || Number(port) > 65535) return "carries a port that is not a whole number from 1 to 65535, written plainly";
545
+ if (path === "") return "has no path";
546
+ return pathProblem(path);
547
+ }
548
+ if (scheme !== scheme.toLowerCase()) return "has an upper-case scheme: a custom scheme is lower-case";
549
+ if (!SCHEME.test(scheme)) return "has a scheme of characters a scheme may not hold";
550
+ if (REFUSED_SCHEMES.includes(scheme)) return "uses a scheme a return address may never use";
551
+ if (rest === "") return "has no path after the scheme";
552
+ if (rest.includes("@")) return "carries userinfo";
553
+ return pathProblem(rest);
554
+ }
504
555
  async function beginSignIn(baseUrl, opts) {
505
556
  const { clientId, redirectUri, resume = null } = opts ?? {};
506
557
  if (typeof clientId !== "string" || clientId === "") throw new TypeError("signInWithOnlyWorlds needs clientId");
507
- if (typeof redirectUri !== "string" || !redirectUri.startsWith("https://")) {
508
- throw new TypeError("signInWithOnlyWorlds: redirectUri must be the registered https: address, as a string");
558
+ const why = redirectProblem(redirectUri);
559
+ if (why !== null) {
560
+ throw new TypeError(`signInWithOnlyWorlds: redirectUri ${why}. Pass the registered return address as a string: https://<host>/<path>, or for a native app http://127.0.0.1:<port>/<path> or http://[::1]:<port>/<path> with the port it bound, or its own scheme, <scheme>://<path>`);
509
561
  }
510
562
  const storage = opts.storage ?? defaultStorage("signInWithOnlyWorlds");
511
563
  const state = randomToken(32);
@@ -528,7 +580,9 @@ async function beginSignIn(baseUrl, opts) {
528
580
  function samePage(a, b) {
529
581
  try {
530
582
  const x = new URL(a), y = new URL(b);
531
- return x.origin === y.origin && x.pathname.replace(/\/$/, "") === y.pathname.replace(/\/$/, "");
583
+ if (x.protocol !== y.protocol || x.host !== y.host) return false;
584
+ if (x.protocol === "https:") return x.pathname.replace(/\/$/, "") === y.pathname.replace(/\/$/, "");
585
+ return x.pathname === y.pathname;
532
586
  } catch {
533
587
  return false;
534
588
  }
@@ -542,7 +596,7 @@ async function completeSignIn(baseUrl, fetchImpl, opts) {
542
596
  const page = new URL(here);
543
597
  const code = page.searchParams.get("code");
544
598
  const state = page.searchParams.get("state");
545
- const hist = globalThis.history;
599
+ const hist = opts.url === void 0 ? globalThis.history : void 0;
546
600
  if (hist && typeof hist.replaceState === "function" && (page.searchParams.has("code") || page.searchParams.has("state"))) {
547
601
  const clean = new URL(here);
548
602
  clean.searchParams.delete("code");
@@ -1868,10 +1922,13 @@ var OwV2Client = class {
1868
1922
  * Start Sign in with OnlyWorlds from a tool's page: mint `state` and a PKCE verifier, keep them
1869
1923
  * under `clientId` in `storage` (sessionStorage by default; in Node pass one), and send the
1870
1924
  * browser to `https://www.onlyworlds.com/signin/authorize` (or only return the URL with
1871
- * `navigate: false`). `redirectUri` is the registered return address as a string, `https:`
1872
- * only, never built from `location.origin`: a tool's registration is read at
1873
- * `GET /api/v2/auth/clients`. `resume` is small JSON handed back by `completeSignIn`. No request
1874
- * is sent; any client, keyless included.
1925
+ * `navigate: false`). `redirectUri` is the registered return address as a string, never built
1926
+ * from `location.origin`: a tool's registration is read at `GET /api/v2/auth/clients`. A web
1927
+ * tool's is `https:`; a tool registered as native may pass a loopback address with the port it
1928
+ * bound for this sign-in (`http://127.0.0.1:<port>/<path>` or `http://[::1]:<port>/<path>`,
1929
+ * registered without the port) or its own scheme as registered (`obsidian://onlyworlds-signin`),
1930
+ * and opens the URL in the system browser with `navigate`. `resume` is small JSON handed back by
1931
+ * `completeSignIn`. No request is sent; any client, keyless included.
1875
1932
  */
1876
1933
  async signInWithOnlyWorlds(opts) {
1877
1934
  only("signInWithOnlyWorlds", opts, ["clientId", "redirectUri", "resume", "storage", "navigate"]);
@@ -1879,7 +1936,9 @@ var OwV2Client = class {
1879
1936
  }
1880
1937
  /**
1881
1938
  * Finish Sign in with OnlyWorlds on the callback page: check `state` against the record and the
1882
- * page against the registered address, take `code` and `state` out of the address bar, trade
1939
+ * page against the registered address (scheme, host with port, and path, each exactly), take
1940
+ * `code` and `state` out of the address bar (only when `url` is not given: a native app passes
1941
+ * the address its loopback server or scheme handler received), trade
1883
1942
  * the code once at `POST /auth/token` with the PKCE verifier and no credential, and return the
1884
1943
  * `ow_a_` token with the account and `resume`. The record is cleared on success and on refusal;
1885
1944
  * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.103.0",
3
+ "version": "4.104.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {