@onlyworlds/sdk 4.103.0 → 4.104.1
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 +17 -0
- package/dist/index.d.ts +26 -10
- package/dist/index.js +71 -12
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,23 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.104.1] - 2026-10-29
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
|
|
12
|
+
- `worldProposals` and `listProposals` say who reads the review queue as the server now answers: the owner's read key (or the write key, with no PIN) reads every row, and a demo key and the keyless public view get a 404. No code changed.
|
|
13
|
+
|
|
14
|
+
## [4.104.0] - 2026-10-29
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **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`.
|
|
19
|
+
|
|
20
|
+
### Fixed
|
|
21
|
+
|
|
22
|
+
- **`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.
|
|
23
|
+
- **`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.
|
|
24
|
+
|
|
8
25
|
## [4.103.0] - 2026-10-29
|
|
9
26
|
|
|
10
27
|
### 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
|
-
/**
|
|
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
|
-
/**
|
|
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. */
|
|
@@ -4593,7 +4604,7 @@ declare class OwV2Client {
|
|
|
4593
4604
|
* owner's and a co-builder's keys, a member's own for any other. `state` is `open` by keel's
|
|
4594
4605
|
* default (not past `expires`), or `lapsed`, `accepted`, `declined`, `all`; `since` keeps rows
|
|
4595
4606
|
* whose `updated_at` is at or after it; `limit` defaults to the client's pageSize. Any member
|
|
4596
|
-
* key that reads the element, a read key included.
|
|
4607
|
+
* key that reads the element, a read key included; the owner's read key reads every row.
|
|
4597
4608
|
*/
|
|
4598
4609
|
listProposals(type: ElementType | string, id: string, opts?: OwProposalQuery): Promise<OwProposalList>;
|
|
4599
4610
|
/**
|
|
@@ -4604,8 +4615,8 @@ declare class OwV2Client {
|
|
|
4604
4615
|
* `open`, `lapsed` and `all`, never `accepted` or `declined`; keel reads at most the 500 newest.
|
|
4605
4616
|
* Every row for the owner's and a co-builder's keys, a member's own for any other. The query is
|
|
4606
4617
|
* listProposals', plus `element` (one element's rows, by id). The cursor is opaque: pass
|
|
4607
|
-
* `next_cursor` back as it came. Any member key, a read key included;
|
|
4608
|
-
*
|
|
4618
|
+
* `next_cursor` back as it came. Any member key, a read key included; the owner's read key (or
|
|
4619
|
+
* write key, no PIN needed) reads every row; a demo key and the keyless public view get a 404.
|
|
4609
4620
|
*/
|
|
4610
4621
|
worldProposals(opts?: OwWorldProposalQuery): Promise<OwWorldProposalList>;
|
|
4611
4622
|
/**
|
|
@@ -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,
|
|
4706
|
-
*
|
|
4707
|
-
*
|
|
4708
|
-
*
|
|
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,
|
|
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
|
-
|
|
508
|
-
|
|
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
|
-
|
|
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");
|
|
@@ -1684,7 +1738,7 @@ var OwV2Client = class {
|
|
|
1684
1738
|
* owner's and a co-builder's keys, a member's own for any other. `state` is `open` by keel's
|
|
1685
1739
|
* default (not past `expires`), or `lapsed`, `accepted`, `declined`, `all`; `since` keeps rows
|
|
1686
1740
|
* whose `updated_at` is at or after it; `limit` defaults to the client's pageSize. Any member
|
|
1687
|
-
* key that reads the element, a read key included.
|
|
1741
|
+
* key that reads the element, a read key included; the owner's read key reads every row.
|
|
1688
1742
|
*/
|
|
1689
1743
|
async listProposals(type, id, opts = {}) {
|
|
1690
1744
|
only("listProposals", opts, ["state", "since", "limit", "cursor"]);
|
|
@@ -1699,8 +1753,8 @@ var OwV2Client = class {
|
|
|
1699
1753
|
* `open`, `lapsed` and `all`, never `accepted` or `declined`; keel reads at most the 500 newest.
|
|
1700
1754
|
* Every row for the owner's and a co-builder's keys, a member's own for any other. The query is
|
|
1701
1755
|
* listProposals', plus `element` (one element's rows, by id). The cursor is opaque: pass
|
|
1702
|
-
* `next_cursor` back as it came. Any member key, a read key included;
|
|
1703
|
-
*
|
|
1756
|
+
* `next_cursor` back as it came. Any member key, a read key included; the owner's read key (or
|
|
1757
|
+
* write key, no PIN needed) reads every row; a demo key and the keyless public view get a 404.
|
|
1704
1758
|
*/
|
|
1705
1759
|
async worldProposals(opts = {}) {
|
|
1706
1760
|
only("worldProposals", opts, ["state", "since", "element", "limit", "cursor"]);
|
|
@@ -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,
|
|
1872
|
-
*
|
|
1873
|
-
*
|
|
1874
|
-
*
|
|
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,
|
|
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
|