Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -79,11 +79,11 @@
"fs-extra": "^11.3.0",
"fumadocs-core": "16.18.0",
"fumadocs-mdx": "15.4.7",
"fumadocs-openapi": "12.6.0",
"fumadocs-openapi": "12.6.5",
"fumadocs-ui": "16.18.0",
"get-port": "^7.1.0",
"is-in-ci": "^2.0.0",
"lucide-react": "1.69.0",
"lucide-react": "1.71.0",
"mustache": "^4.2.0",
"neverthrow": "^8.2.0",
"open": "^8.4.0",
Expand Down
81 changes: 44 additions & 37 deletions pnpm-lock.yaml

Large diffs are not rendered by default.

6 changes: 6 additions & 0 deletions pnpm-workspace.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,10 @@ overrides:
# the two on Node 22.14, and installs all the same.
'fumadocs-openapi>chokidar': ^5.0.0
'fumadocs-openapi>undici': 7.30.1
# 12.6.5 asks for @scalar/json-magic 0.19 as well, whose floor is Node 22.19 for the undici 8 it pins.
# Held at 0.16, which 12.6.0 shipped with. Unlike the two above, the CLI loads this one: fumadocs-openapi
# reads a specification through its magic proxy, which 0.19 rewrote. So the tests here run 0.16's proxy
# and an `npm install -g` runs 0.19's, with two more EBADENGINE warnings on Node 22.14, for it and for
# that undici; the portal tests install the packed CLI as npm does.
'fumadocs-openapi>@scalar/json-magic': ^0.16.1

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI tests @scalar/json-magic 0.16.1, while customers get 0.19.1.

Because of this override, every CI job runs json-magic 0.16.1. An npm install -g of the CLI ignores pnpm overrides and gets 0.19.1. That code runs in two places:

  • in the CLI, where create-page.js and dereference.js call createMagicProxy
  • in the portal's browser bundle, where operation.js and usage-tabs.js import getRaw

I checked that 0.19 is safe on the path we use. fumadocs-openapi imports only createMagicProxy and getRaw from @scalar/json-magic/magic-proxy, and both exist in 0.16 and 0.19. In 0.19.1 the magic-proxy code doesn't load undici; only bundle/plugins/fetch-urls does. So the extra EBADENGINE warnings on Node 22.14 don't affect this path at runtime.

The gap is that nothing automated checks 0.19 before this merges. portal_tests.yml installs the packed CLI the way npm does, but it only runs on push to dev. It also has a workflow_dispatch trigger, so could you:

  1. Run portal_tests.yml on this branch (gh workflow run portal_tests.yml --ref chore/fumadocs-openapi-12-6-5) and link the run here before merging? Then the manual 0.19 checks in the description are backed by CI.
  2. Open an issue to remove this pin, with its condition (the CLI's Node floor reaching 22.19), so it doesn't live only in this comment.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First, an apology: you had already started a run on this branch (44030994779), and my dispatch cancelled it 32 minutes in, because the workflow cancels a run in progress on the same ref. I should have listed the runs first. I restarted one, and it has finished.

The run: https://github.com/apimatic/apimatic-cli/actions/runs/44035040377, on b105d56. The one commit after it changes a comment only.

What it backs. With the packed CLI installed as npm does, so with json-magic 0.19.1, these pass: generate the portal, visual, visual — nav.json, generate the auth portal and generate the petstore portal. So CI now covers 0.19 for building a portal and for the visual baselines.

It is not green, and neither is dev. Your baseline run on dev (44031027356, at 8e394e5) fails the same way. The same 16 tests fail in both runs, with the same messages:

  • artifacts: the petstore llms.txt baseline lacks the listPetVisits line.
  • functional: every auth playground test times out on locator('#nd-page').locator('form').first(). That is the inline playground form, which the suite's main still drives; 12.6 moved the playground into a dialog. Each test waits out its two minutes, so the job runs into its 45-minute limit.

The branch run got two tests further than dev before that limit, the digest test and the petstore servers test, and both stop on the same missing form.

So neither failure comes from this PR, but the playground tests cannot vouch for 0.19, or for anything else in the playground, until the suite is updated. apimatic/v4-test-automation#26 is that update for 12.6; it is open and conflicts with main, and the new field rows of 12.6.3 will likely need the page object changed again.

The issue: apimatic/apimatic-io#2353, with the condition (the Node floor reaching 22.19, in engines.node and in the test matrix) and the steps to take the pin out.

I checked your reading of the code paths and agree. To be exact about the files: createMagicProxy is in utils/document/dereference.js, and getRaw in operation.js, ui/operation/usage-tabs.js, utils/create-page.js, utils/get-example-requests.js and utils/schema.js. In 0.19.1 nothing the magic proxy imports reaches undici; only bundle/plugins/fetch-urls/fetch-public-url.js loads it.

'@types/node': $@types/node
2 changes: 0 additions & 2 deletions portal-template/src/components/playground.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,6 @@ export default function Playground() {
}),
[]
);
// Fumadocs takes a returned sign-in's answer out of the address in the effects of the playground below this one.
useEffect(() => analytics.loadTags(), []);
return (
<SentAt value={sentAt}>
<PlaygroundClient fetchOptions={fetchOptions} components={components} />
Expand Down
2 changes: 1 addition & 1 deletion portal-template/src/components/usage-tabs.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ function SampleCode({ sample }: Readonly<{ sample: CodeSample }>) {
return <CodeBlock lang={sample.lang} code={source} codeblock={SHRINKING_BLOCK} />;
}

// Follows the playground's edits, typed credentials included, so it carries the playground's replay markers.
// Follows the playground's edits, so it carries its replay markers; Fumadocs writes a credential as `********`.
function CurlCode() {
const { CodeBlock } = useComponents();
const code = useCodeUsage(CURL_USAGE_ID);
Expand Down
8 changes: 2 additions & 6 deletions portal-template/src/lib/analytics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -83,11 +83,6 @@ export class Analytics {
insertTags(this.live);
}

/** The tags held back while the address held an OAuth answer, once something has taken it out. */
public loadTags(): void {
insertTags(this.live);
}

/** `href` is the page the event belongs to, when the caller saw the address move on first. */
public report<E extends PortalEventName>(name: E, params: PortalEvents[E], href = window.location.href): void {
if (isOAuthCallbackPath(new URL(href).pathname)) return;
Expand All @@ -101,7 +96,8 @@ export class Analytics {

public reportPageView(): void {
if (isOAuthCallbackPath(window.location.pathname)) return;
this.loadTags();
// The tags a start on the OAuth callback left out, now that the reader has moved on from it.
insertTags(this.live);
const page = pageLocation(window.location.href, this.settings.keepQueryParams);
if (page === this.lastPageView) return;
this.previousPageView = this.lastPageView;
Expand Down
24 changes: 10 additions & 14 deletions portal-template/src/lib/oauth-callback.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,15 @@ export function isOAuthCallbackPath(pathname: string, base?: string): boolean {
return pathname.replace(/\/$/, '') === withBasePath(oauthCallbackPath, base);
}

/** The callback's address always holds a provider's answer; a page a sign-in returned to does until the playground reads it. */
export function holdsOAuthAnswer({ pathname, search, hash }: Pick<Location, 'pathname' | 'search' | 'hash'>): boolean {
// Fumadocs sends a `state` with every authorization, and the answer carries it back in the query or the `#` part.
return (
isOAuthCallbackPath(pathname) ||
new URLSearchParams(search).has('state') ||
new URLSearchParams(hash.slice(1)).has('state')
);
}

/** Where the playground notes the path of the page that started the flow before it leaves: this tab's session storage. */
const STARTING_PAGE_KEY = 'fumadocs-openapi-oauth';

/** Where the playground looks for the callback's address, the provider's answer in it, once its page loads again. */
const ANSWER_KEY = 'fumadocs-openapi-oauth-returned';

/** What the callback does with the browser that lands on it. */
export type OAuthCallback =
/** Sends it back to the page that started the flow, with the provider's answer still attached. */
/** Sends it back to the page that started the flow, at its own address: the answer goes through the session. */
| { kind: 'return'; url: string }
/** Stays, to show the error the provider ended the authorization with, and a link back to that page. */
| { kind: 'providerError'; error: string; description: string | null; page: string }
Expand Down Expand Up @@ -56,7 +49,7 @@ export function oauthCallback(
} catch {
return { kind: 'unknownPage' };
}
// Anything else is an open redirect, carrying the authorization code to another site.
// Anything else is an open redirect.
if (page.origin !== location.origin) return { kind: 'unknownPage' };

const query = new URLSearchParams(location.search);
Expand All @@ -67,8 +60,6 @@ export function oauthCallback(
}

// Whole, not as a path: a path of `//evil.test/x` would be read as another site's address.
page.search = location.search;
page.hash = location.hash;
return { kind: 'return', url: page.href };
}

Expand All @@ -82,3 +73,8 @@ export function takeStartingPage(): string | null {
sessionStorage.removeItem(STARTING_PAGE_KEY);
return page;
}

/** Leaves the callback's address for the playground, as Fumadocs' handler does: no page's address holds the answer. */
export function leaveAnswer(callbackAddress: string): void {
sessionStorage.setItem(ANSWER_KEY, callbackAddress);
}
11 changes: 8 additions & 3 deletions portal-template/src/lib/vendor-tags.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { holdsOAuthAnswer } from './oauth-callback';
import { isOAuthCallbackPath } from './oauth-callback';
import type { PortalAnalytics } from './portal-types';

type Gtag = (...command: unknown[]) => void;
Expand Down Expand Up @@ -54,9 +54,14 @@ export const adapters: { [V in Vendor]: (settings: PortalAnalytics) => Adapter |
}
};

/** None while the address holds an OAuth answer, which the tags read for themselves; each once, so a later call adds the rest. */
/**
* None on the OAuth callback, whose address holds the provider's answer; each once, so a later call adds the rest.
* The page a sign-in returns to loads them at once, although the answer waits in the tab's session storage until
* a playground reads it: tags read the address, not the storage, so that window is accepted. On a page that mounts
* no playground the answer stays until one mounts in the tab or the tab closes, as with Fumadocs' own handler.
*/
export function insertTags(live: Adapter[]): void {
if (holdsOAuthAnswer(window.location)) return;
if (isOAuthCallbackPath(window.location.pathname)) return;
for (const { script: src } of live) {
if (document.head.querySelector(`script[src="${src}"]`) !== null) continue;
const script = document.createElement('script');
Expand Down
13 changes: 11 additions & 2 deletions portal-template/src/routes/oauth.callback.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,13 @@ import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { useEffect, useState } from 'react';
import { AuthorizationFailure } from '@/components/authorization-failure';
import { baseOptions } from '@/lib/layout.shared';
import { oauthCallback, takeStartingPage, type OAuthCallback, type OAuthCallbackFailure } from '@/lib/oauth-callback';
import {
leaveAnswer,
oauthCallback,
takeStartingPage,
type OAuthCallback,
type OAuthCallbackFailure
} from '@/lib/oauth-callback';
import { portal } from '@/lib/portal';

// Published portals are static, so this page does in the browser what Fumadocs'
Expand Down Expand Up @@ -32,7 +38,10 @@ let completion: OAuthCallback | undefined;
function completeAuthorization(): OAuthCallback {
if (completion === undefined) {
completion = oauthCallback(takeStartingPage(), window.location);
if (completion.kind === 'return') window.location.replace(completion.url);
if (completion.kind === 'return') {
leaveAnswer(window.location.href);
window.location.replace(completion.url);
}
}
return completion;
}
Expand Down
23 changes: 7 additions & 16 deletions test/portal-template/analytics.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -415,8 +415,8 @@ describe('Analytics', () => {
});
});

describe('after a playground sign-in', () => {
it('reports with the OAuth answer stripped from page_location', () => {
describe('at an address that holds an OAuth answer', () => {
it('reports with the answer stripped from page_location', () => {
const page = browser('https://docs.test/api/pets/listPets#access_token=xyz&state=123', 'List pets');
const analytics = new Analytics(withBoth);

Expand All @@ -432,26 +432,17 @@ describe('Analytics', () => {
});
});

describe('on the page a playground sign-in returned to', () => {
const answered = 'https://docs.test/api/pets/listPets?code=abc&state=123';

it('holds the tags back while the answer is in the address, and loads them once the playground took it out', () => {
const page = browser(answered, 'List pets');
// A sign-in's answer reaches the playground through the tab's session, so no page but the callback waits for one.
describe('on a page whose own link carries a state parameter', () => {
it('loads the tags at once, and reports the page without the parameter', () => {
const page = browser(`${quickstart}?state=CA`);
const analytics = new Analytics(withBoth);

analytics.start();
analytics.reportPageView();
analytics.loadTags();

expect(page.scripts).to.be.empty;
expect(pageViews(page.dataLayer())).to.have.length(1);

page.go('https://docs.test/api/pets/listPets');
analytics.loadTags();
analytics.reportPageView();

expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, GA4_SCRIPT]);
expect(pageViews(page.dataLayer())).to.have.length(1);
expect(pageViews(page.dataLayer())).to.deep.equal([quickstartView]);
});
});

Expand Down
105 changes: 61 additions & 44 deletions test/portal-template/oauth-callback.test.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
import { runInNewContext } from 'node:vm';
import { expect } from 'chai';
import type { SecuritySchemeObject } from 'fumadocs-openapi';
import { requestOAuthToken } from 'fumadocs-openapi/playground';
import { createOpenAPI } from 'fumadocs-openapi/server';
import {
holdsOAuthAnswer,
isOAuthCallbackPath,
leaveAnswer,
oauthCallback,
oauthCallbackPath,
takeStartingPage
Expand Down Expand Up @@ -41,26 +43,6 @@ describe('isOAuthCallbackPath', () => {
});
});

describe('holdsOAuthAnswer', () => {
const at = (href: string) => holdsOAuthAnswer(new URL(href));

it('holds on the callback, with or without an answer', () => {
expect(at('https://docs.test/oauth/callback')).to.be.true;
expect(at('https://docs.test/oauth/callback?code=abc&state=123')).to.be.true;
});

it('holds on a page a sign-in returned to, with a code, a token or an error', () => {
expect(at('https://docs.test/api/pets/listPets?code=abc&state=123')).to.be.true;
expect(at('https://docs.test/api/pets/listPets#access_token=xyz&token_type=Bearer&state=123')).to.be.true;
expect(at('https://docs.test/api/pets/listPets?error=access_denied&state=123')).to.be.true;
});

it('does not hold on any other address, a query or a # part of its own included', () => {
expect(at('https://docs.test/api/pets/listPets')).to.be.false;
expect(at('https://docs.test/guides/quickstart?utm_source=mail&code=SAVE10#install')).to.be.false;
});
});

describe('takeStartingPage', () => {
const origin = 'https://docs.test';
const pathname = '/api/pets/pets/listPets';
Expand Down Expand Up @@ -107,15 +89,15 @@ describe('takeStartingPage', () => {
}
});

it("sends the provider's answer back to the page the playground noted before it left", async () => {
it('sends the browser back to the page the playground noted before it left', async () => {
await requestOAuthToken(scheme, 'authorizationCode', flow);
expect(leftFor?.origin, 'left for the provider').to.equal('https://provider.test');
expect(leftFor?.searchParams.get('redirect_uri')).to.equal(`${origin}${oauthCallbackPath}`);
const state = leftFor?.searchParams.get('state');

const callback = oauthCallback(takeStartingPage(), { origin, search: `?code=abc&state=${state}`, hash: '' });

expect(callback).to.deep.equal({ kind: 'return', url: `${origin}${pathname}?code=abc&state=${state}` });
expect(callback).to.deep.equal({ kind: 'return', url: `${origin}${pathname}` });
});

it('takes the note once', async () => {
Expand All @@ -126,41 +108,76 @@ describe('takeStartingPage', () => {
});
});

describe('oauthCallback', () => {
const origin = 'https://docs.test';
const answered = (search: string, hash = '') => ({ origin, search, hash });

it("sends the authorization code back to the page that started the flow, in the provider's query", () => {
const callback = oauthCallback('/api/pets/pets/listPets', answered('?code=abc&state=123'));
// Fumadocs' handler is a server route. Inlined, its page carries the script a static site would serve.
describe('leaveAnswer', () => {
const tab = globalThis as { sessionStorage?: unknown };
const callbackAddress = 'https://docs.test/oauth/callback?code=abc&state=123';
/** A tab's session in which the playground has noted its page, as the test above holds it does. */
const session = () => {
const storage = new Map([['fumadocs-openapi-oauth', '/api/pets/pets/listPets']]);
return {
// What a callback left for the playground, the note aside: Fumadocs' handler keeps it, ours takes it.
left: () => [...storage].filter(([key]) => key !== 'fumadocs-openapi-oauth'),
getItem: (key: string) => storage.get(key) ?? null,
setItem: (key: string, value: string) => void storage.set(key, value),
removeItem: (key: string) => void storage.delete(key)
};
};

expect(callback).to.deep.equal({
kind: 'return',
url: 'https://docs.test/api/pets/pets/listPets?code=abc&state=123'
afterEach(() => {
delete tab.sessionStorage;
});

it("leaves what Fumadocs' own handler leaves for the playground, and goes to the same page", async () => {
const handler = createOpenAPI().createOAuthHandler({ inline: true });
const script =
/<script>([\s\S]*)<\/script>/.exec(await handler(new globalThis.Request(callbackAddress)).text())?.[1] ?? '';
const theirs = session();
let theirPage = '';
runInNewContext(script, {
sessionStorage: theirs,
location: { href: callbackAddress, origin: 'https://docs.test', replace: (url: string) => void (theirPage = url) }
});

const ours = session();
tab.sessionStorage = ours;
const callback = oauthCallback(takeStartingPage(), new URL(callbackAddress));
leaveAnswer(callbackAddress);

expect(theirs.left(), "what Fumadocs' handler left").to.deep.equal([
['fumadocs-openapi-oauth-returned', callbackAddress]
]);
expect(ours.left()).to.deep.equal(theirs.left());
expect(callback).to.deep.equal({ kind: 'return', url: theirPage });
});
});

// The implicit flow answers in the fragment, which a browser never sends to a server either.
it("sends the implicit flow's token back in the provider's fragment", () => {
const callback = oauthCallback('/api/pets/pets/listPets', answered('', '#access_token=xyz&state=123'));
describe('oauthCallback', () => {
const origin = 'https://docs.test';
const answered = (search: string, hash = '') => ({ origin, search, hash });

expect(callback).to.deep.equal({
kind: 'return',
url: 'https://docs.test/api/pets/pets/listPets#access_token=xyz&state=123'
});
// The authorization code flow answers in the query, the implicit one in the fragment.
it('sends the browser back to the page at its own address, whichever way the provider answered', () => {
for (const answer of [answered('?code=abc&state=123'), answered('', '#access_token=xyz&state=123')]) {
expect(oauthCallback('/api/pets/pets/listPets', answer)).to.deep.equal({
kind: 'return',
url: 'https://docs.test/api/pets/pets/listPets'
});
}
});

// The playground notes `location.pathname`, which the browser has already percent-encoded.
it('keeps an encoded page path as the playground wrote it', () => {
const callback = oauthCallback('/api/pets/Get%20Pets', answered('?code=abc'));

expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test/api/pets/Get%20Pets?code=abc' });
expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test/api/pets/Get%20Pets' });
});

// As a bare path, `//evil.test/x?code=abc` would send the code to evil.test.
it('keeps the code on this site for a page whose path reads as another site', () => {
// As a bare path, `//evil.test/x` would send the browser to evil.test.
it('stays on this site for a page whose path reads as another site', () => {
const callback = oauthCallback('https://docs.test//evil.test/x', answered('?code=abc', '#access_token=xyz'));

expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test//evil.test/x?code=abc#access_token=xyz' });
expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test//evil.test/x' });
});

// The playground's own return handling finds no code or token in it, and says nothing.
Expand Down Expand Up @@ -201,7 +218,7 @@ describe('oauthCallback', () => {
});

// The last is the path of a page at `//a b/x`, which does not read as an address at all.
it('refuses to send the code to another site, or to a page that does not read as one', () => {
it('refuses to send the browser to another site, or to a page that does not read as one', () => {
for (const page of ['https://evil.test/steal', '//evil.test/steal', '//a%20b/x']) {
expect(oauthCallback(page, answered('?code=abc')), page).to.deep.equal({ kind: 'unknownPage' });
}
Expand Down
Loading