Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): deferred share deep-link through first install (#1810)

Andrew Mikofalvy2e2fcdd51ca5
diff --git a/docs/src/app/continue/done/route.ts b/docs/src/app/continue/done/route.ts
new file mode 100644
index 000000000..53b71dd23
--- /dev/null
+++ b/docs/src/app/continue/done/route.ts
@@ -0,0 +1,42 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import { PENDING_SHARE_COOKIE } from '@/lib/deferred-share';
+
+export const dynamic = 'force-dynamic';
+
+export function GET(_request: NextRequest): NextResponse {
+ const body = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>Open Knowledge</title>
+<style>
+ :root { color-scheme: light dark; }
+ body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+ background: #faf9f7; color: #1a1a1a; }
+ @media (prefers-color-scheme: dark) { body { background: #16151a; color: #f2f1ef; } }
+ .card { max-width: 28rem; padding: 2rem; text-align: center; }
+ h1 { font-size: 1.5rem; font-weight: 500; margin: 0 0 0.75rem; }
+ p { margin: 0; line-height: 1.6; opacity: 0.7; font-size: 0.95rem; }
+</style>
+</head>
+<body>
+<div class="card" data-testid="continue-done">
+<h1>Opening in Open Knowledge…</h1>
+<p>You can close this tab and return to the app.</p>
+</div>
+</body>
+</html>`;
+
+ const response = new NextResponse(body, {
+ status: 200,
+ headers: {
+ 'content-type': 'text/html; charset=utf-8',
+ 'cache-control': 'no-store',
+ },
+ });
+ response.cookies.delete(PENDING_SHARE_COOKIE);
+ return response;
+}
diff --git a/docs/src/app/continue/page.tsx b/docs/src/app/continue/page.tsx
new file mode 100644
index 000000000..19d567f3d
--- /dev/null
+++ b/docs/src/app/continue/page.tsx
@@ -0,0 +1,105 @@
+import { ArrowRightIcon, DownloadIcon } from 'lucide-react';
+import { cookies } from 'next/headers';
+import Image from 'next/image';
+import Link from 'next/link';
+import { redirect } from 'next/navigation';
+import {
+ decideContinue,
+ NONCE_PARAM,
+ PENDING_SHARE_COOKIE,
+ PORT_PARAM,
+} from '@/lib/deferred-share';
+import { SPLASH_DOWNLOAD_URL } from '@/lib/share-splash';
+
+export const dynamic = 'force-dynamic';
+
+interface ContinuePageProps {
+ searchParams: Promise<Record<string, string | string[] | undefined>>;
+}
+
+function firstParam(value: string | string[] | undefined): string | null {
+ if (Array.isArray(value)) return value[0] ?? null;
+ return value ?? null;
+}
+
+export default async function ContinuePage({ searchParams }: ContinuePageProps) {
+ const params = await searchParams;
+ const cookieStore = await cookies();
+
+ const decision = decideContinue({
+ cookieToken: cookieStore.get(PENDING_SHARE_COOKIE)?.value ?? null,
+ port: firstParam(params[PORT_PARAM]),
+ nonce: firstParam(params[NONCE_PARAM]),
+ });
+
+ if (decision.kind === 'redeem') {
+ redirect(decision.location);
+ }
+
+ return (
+ <main className="relative min-h-screen bg-[var(--slide-bg)] font-[family-name:var(--font-dm-sans)]">
+ <Image
+ src="/ok-logo.png"
+ alt=""
+ width={64}
+ height={64}
+ className="pointer-events-none absolute top-8 right-8 z-10 size-10 md:top-12 md:right-12 md:size-12"
+ aria-hidden="true"
+ />
+
+ <section className="px-6 pt-32 pb-16 md:pt-44 md:pb-20">
+ <div className="mx-auto max-w-3xl">
+ <p className="mb-6 text-sm font-medium italic text-[var(--slide-accent-strong)]">
+ Welcome to Open Knowledge
+ </p>
+
+ <h1 className="text-3xl font-light tracking-tight text-[var(--slide-text)] sm:text-4xl lg:text-[3.25rem] lg:leading-[1.1]">
+ You&rsquo;re all set.
+ </h1>
+
+ <p className="mt-8 text-lg leading-relaxed text-[var(--slide-muted)]">
+ Open Knowledge is a local-first, markdown-native knowledge base where you and your AI
+ agents co-create. Open the app to create your first project, or connect an existing
+ GitHub repository.
+ </p>
+
+ <div className="mt-12 flex flex-wrap items-center gap-4">
+ <Link
+ href="/docs"
+ data-testid="continue-getting-started"
+ className="slide-btn-primary inline-flex items-center gap-2 rounded-lg px-6 py-3 text-sm font-medium transition-opacity focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--slide-accent-strong)]"
+ >
+ Read the getting-started guide
+ <ArrowRightIcon className="size-4" aria-hidden="true" />
+ </Link>
+ </div>
+
+ <div
+ className="mt-12 border-t border-[var(--slide-border,rgba(0,0,0,0.08))] pt-8"
+ data-testid="continue-share-recovery"
+ >
+ <p className="text-sm font-medium text-[var(--slide-text)]">
+ Were you sent a share link?
+ </p>
+ <p className="mt-2 text-sm leading-relaxed text-[var(--slide-muted)]">
+ If you opened Open Knowledge from a shared document, click that link again and choose{' '}
+ <span className="font-medium">Open in Open Knowledge</span> to jump straight to it. If
+ you don&rsquo;t have the app yet,{' '}
+ <a
+ href={SPLASH_DOWNLOAD_URL}
+ className="font-medium text-[var(--slide-text)] underline underline-offset-4 transition-colors hover:text-[var(--slide-accent)]"
+ >
+ download it for macOS
+ </a>
+ .
+ </p>
+ <p className="mt-3 inline-flex items-center gap-2 text-sm text-[var(--slide-muted)]">
+ <DownloadIcon className="size-4" aria-hidden="true" />
+ <span>Open Knowledge is macOS-only in v1.</span>
+ </p>
+ </div>
+ </div>
+ </section>
+ </main>
+ );
+}
diff --git a/docs/src/app/d/[encoded]/download/route.ts b/docs/src/app/d/[encoded]/download/route.ts
new file mode 100644
index 000000000..671482f1e
--- /dev/null
+++ b/docs/src/app/d/[encoded]/download/route.ts
@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+import { buildPendingShareCookie } from '@/lib/deferred-share';
+import { buildSplashViewModel, SPLASH_DOWNLOAD_URL } from '@/lib/share-splash';
+
+export async function GET(
+ _request: Request,
+ { params }: { params: Promise<{ encoded: string }> },
+): Promise<NextResponse> {
+ const { encoded } = await params;
+ const response = NextResponse.redirect(SPLASH_DOWNLOAD_URL, 302);
+
+ const view = buildSplashViewModel(encoded);
+ if (view.kind === 'ok') {
+ response.cookies.set(buildPendingShareCookie(encoded));
+ }
+
+ return response;
+}
diff --git a/docs/src/app/d/[encoded]/page.tsx b/docs/src/app/d/[encoded]/page.tsx
index 3375f956f..d57837935 100644
--- a/docs/src/app/d/[encoded]/page.tsx
+++ b/docs/src/app/d/[encoded]/page.tsx
@@ -132,7 +132,7 @@ export default async function SplashPage({ params }: SplashPageProps) {
)}
<SplashCtaCluster
- downloadUrl={SPLASH_DOWNLOAD_URL}
+ downloadUrl={`/d/${encoded}/download`}
customSchemeUrl={view.customSchemeUrl}
githubUrl={view.githubUrl}
/>
diff --git a/docs/src/app/d/[encoded]/splash-cta-cluster.tsx b/docs/src/app/d/[encoded]/splash-cta-cluster.tsx
index ec5e93760..6db54697c 100644
--- a/docs/src/app/d/[encoded]/splash-cta-cluster.tsx
+++ b/docs/src/app/d/[encoded]/splash-cta-cluster.tsx
@@ -18,11 +18,35 @@ export function SplashCtaCluster({
}: SplashCtaClusterProps) {
const [attempting, setAttempting] = useState(false);
const [handoffFailed, setHandoffFailed] = useState(false);
+ const [downloadClicked, setDownloadClicked] = useState(false);
+ const [showReopen, setShowReopen] = useState(false);
const attemptCleanupRef = useRef<(() => void) | null>(null);
const fallbackCtaRef = useRef<HTMLAnchorElement | null>(null);
+ const reopenCtaRef = useRef<HTMLAnchorElement | null>(null);
useEffect(() => () => attemptCleanupRef.current?.(), []);
+ useEffect(() => {
+ if (!downloadClicked) return;
+ function onRefocus() {
+ if (document.visibilityState === 'visible') setShowReopen(true);
+ }
+ window.addEventListener('focus', onRefocus);
+ document.addEventListener('visibilitychange', onRefocus);
+ return () => {
+ window.removeEventListener('focus', onRefocus);
+ document.removeEventListener('visibilitychange', onRefocus);
+ };
+ }, [downloadClicked]);
+
+ useEffect(() => {
+ if (showReopen) reopenCtaRef.current?.focus();
+ }, [showReopen]);
+
+ const handleDownloadClick = () => {
+ setDownloadClicked(true);
+ };
+
useEffect(() => {
if (handoffFailed) fallbackCtaRef.current?.focus();
}, [handoffFailed]);
@@ -63,6 +87,27 @@ export function SplashCtaCluster({
return (
<div className="mt-12">
+ {showReopen ? (
+ <div
+ className="mb-6 rounded-lg border border-[var(--slide-border,rgba(0,0,0,0.08))] p-4"
+ data-testid="splash-reopen-prompt"
+ >
+ <p className="text-sm text-[var(--slide-muted)]">
+ Installed Open Knowledge? Open it to land on this share.
+ </p>
+ <a
+ ref={reopenCtaRef}
+ href={customSchemeUrl}
+ onClick={handleOpenClick}
+ data-testid="splash-reopen-cta"
+ className="slide-btn-primary mt-3 inline-flex touch-manipulation items-center gap-2 rounded-lg px-6 py-3 text-sm font-medium transition-[opacity,transform] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--slide-accent-strong)]"
+ >
+ {attempting ? 'Opening…' : 'Open in Open Knowledge'}
+ <ArrowRightIcon className="size-4" aria-hidden="true" />
+ </a>
+ </div>
+ ) : null}
+
<div className="flex flex-wrap items-center gap-4">
<a
href={customSchemeUrl}
@@ -95,6 +140,7 @@ export function SplashCtaCluster({
<a
ref={fallbackCtaRef}
href={downloadUrl}
+ onClick={handleDownloadClick}
data-testid="splash-download-fallback-cta"
className="slide-btn-primary mt-3 inline-flex touch-manipulation items-center gap-2 rounded-lg px-6 py-3 text-sm font-medium transition-[opacity,transform] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--slide-accent-strong)]"
>
@@ -107,6 +153,7 @@ export function SplashCtaCluster({
Don&rsquo;t have the app?{' '}
<a
href={downloadUrl}
+ onClick={handleDownloadClick}
data-testid="splash-download-cta"
className="touch-manipulation font-medium text-[var(--slide-text)] underline underline-offset-4 transition-colors hover:text-[var(--slide-accent)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--slide-accent)] focus-visible:rounded"
>
diff --git a/docs/src/lib/deferred-share.test.ts b/docs/src/lib/deferred-share.test.ts
new file mode 100644
index 000000000..3880e07e1
--- /dev/null
+++ b/docs/src/lib/deferred-share.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test';
+import {
+ buildPendingShareCookie,
+ decideContinue,
+ PENDING_SHARE_COOKIE,
+ PENDING_SHARE_MAX_AGE_SECONDS,
+} from './deferred-share.ts';
+
+const VALID_TOKEN = 'AWh0dHBzOi8vZ2l0aHViLmNvbS9pbmtlZXAvdGVjaC1pcG9z';
+const VALID_NONCE = 'a1b2c3d4e5f60718293a4b5c6d7e8f90';
+
+describe('buildPendingShareCookie', () => {
+ test('sets HttpOnly/Secure/Lax first-party cookie with the 7-day max-age', () => {
+ const cookie = buildPendingShareCookie(VALID_TOKEN);
+ expect(cookie.name).toBe(PENDING_SHARE_COOKIE);
+ expect(cookie.value).toBe(VALID_TOKEN);
+ expect(cookie.httpOnly).toBe(true);
+ expect(cookie.secure).toBe(true);
+ expect(cookie.sameSite).toBe('lax');
+ expect(cookie.path).toBe('/');
+ expect(cookie.maxAge).toBe(PENDING_SHARE_MAX_AGE_SECONDS);
+ expect(PENDING_SHARE_MAX_AGE_SECONDS).toBe(604800);
+ });
+});
+
+describe('decideContinue — redeem branch', () => {
+ test('redirects the pending token to the loopback listener when all inputs are valid', () => {
+ const decision = decideContinue({
+ cookieToken: VALID_TOKEN,
+ port: '52431',
+ nonce: VALID_NONCE,
+ });
+ expect(decision.kind).toBe('redeem');
+ if (decision.kind !== 'redeem') throw new Error('unreachable');
+ expect(decision.location).toBe(
+ `http://127.0.0.1:52431/redeem?token=${VALID_TOKEN}&nonce=${VALID_NONCE}`,
+ );
+ });
+
+ test('host is hardcoded loopback — only the numeric port is taken from input', () => {
+ const decision = decideContinue({ cookieToken: VALID_TOKEN, port: '1', nonce: VALID_NONCE });
+ if (decision.kind !== 'redeem') throw new Error('expected redeem');
+ expect(decision.location.startsWith('http://127.0.0.1:1/redeem?')).toBe(true);
+ });
+});
+
+describe('decideContinue — welcome branch', () => {
+ test('no handshake params → welcome, cookie retained (direct visit must not burn the pairing)', () => {
+ const decision = decideContinue({ cookieToken: VALID_TOKEN, port: null, nonce: null });
+ expect(decision).toEqual({ kind: 'welcome', clearCookie: false });
+ });
+
+ test('valid params but no cookie → welcome, nothing to clear', () => {
+ const decision = decideContinue({ cookieToken: null, port: '52431', nonce: VALID_NONCE });
+ expect(decision).toEqual({ kind: 'welcome', clearCookie: false });
+ });
+
+ test('valid params but malformed cookie → welcome + clear the bad cookie', () => {
+ const decision = decideContinue({
+ cookieToken: 'not valid base64url!!',
+ port: '52431',
+ nonce: VALID_NONCE,
+ });
+ expect(decision).toEqual({ kind: 'welcome', clearCookie: true });
+ });
+
+ test.each([
+ ['port out of range (0)', '0', VALID_NONCE],
+ ['port out of range (70000)', '70000', VALID_NONCE],
+ ['non-numeric port', '52431a', VALID_NONCE],
+ ['non-hex nonce', '52431', 'ZZZZ'],
+ ['nonce too short', '52431', 'a1b2'],
+ ])('rejects %s → welcome (no redeem)', (_label, port, nonce) => {
+ const decision = decideContinue({ cookieToken: VALID_TOKEN, port, nonce });
+ expect(decision.kind).toBe('welcome');
+ });
+
+ test('over-length token is rejected even with valid params', () => {
+ const decision = decideContinue({
+ cookieToken: 'A'.repeat(5000),
+ port: '52431',
+ nonce: VALID_NONCE,
+ });
+ expect(decision.kind).toBe('welcome');
+ if (decision.kind !== 'welcome') throw new Error('unreachable');
+ expect(decision.clearCookie).toBe(true);
+ });
+});
diff --git a/docs/src/lib/deferred-share.ts b/docs/src/lib/deferred-share.ts
new file mode 100644
index 000000000..298df0ad1
--- /dev/null
+++ b/docs/src/lib/deferred-share.ts
@@ -0,0 +1,84 @@
+export const PENDING_SHARE_COOKIE = 'ok_pending_share';
+
+export const PENDING_SHARE_MAX_AGE_SECONDS = 7 * 24 * 60 * 60;
+
+export const PORT_PARAM = 'port';
+export const NONCE_PARAM = 'nonce';
+
+const REDEEM_TOKEN_PARAM = 'token';
+const REDEEM_NONCE_PARAM = 'nonce';
+
+const REDEEM_PATH = '/redeem';
+
+const MAX_TOKEN_LENGTH = 4096;
+
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+const NONCE_RE = /^[a-f0-9]{16,128}$/;
+
+export interface PendingShareCookieInit {
+ name: typeof PENDING_SHARE_COOKIE;
+ value: string;
+ httpOnly: true;
+ secure: true;
+ sameSite: 'lax';
+ path: '/';
+ maxAge: number;
+}
+
+export function buildPendingShareCookie(token: string): PendingShareCookieInit {
+ return {
+ name: PENDING_SHARE_COOKIE,
+ value: token,
+ httpOnly: true,
+ secure: true,
+ sameSite: 'lax',
+ path: '/',
+ maxAge: PENDING_SHARE_MAX_AGE_SECONDS,
+ };
+}
+
+function isValidToken(token: string): boolean {
+ return token.length > 0 && token.length <= MAX_TOKEN_LENGTH && BASE64URL_RE.test(token);
+}
+
+function isValidPort(port: string | null): port is string {
+ if (port === null || !/^\d+$/.test(port)) return false;
+ const n = Number(port);
+ return Number.isInteger(n) && n >= MIN_PORT && n <= MAX_PORT;
+}
+
+function isValidNonce(nonce: string | null): nonce is string {
+ return nonce !== null && NONCE_RE.test(nonce);
+}
+
+export type ContinueDecision =
+ | { kind: 'redeem'; location: string }
+ | { kind: 'welcome'; clearCookie: boolean };
+
+export function decideContinue(input: {
+ cookieToken: string | undefined | null;
+ port: string | null;
+ nonce: string | null;
+}): ContinueDecision {
+ const cookieToken = input.cookieToken ?? '';
+
+ if (!isValidPort(input.port) || !isValidNonce(input.nonce)) {
+ return { kind: 'welcome', clearCookie: false };
+ }
+
+ if (!isValidToken(cookieToken)) {
+ return { kind: 'welcome', clearCookie: cookieToken.length > 0 };
+ }
+
+ const params = new URLSearchParams({
+ [REDEEM_TOKEN_PARAM]: cookieToken,
+ [REDEEM_NONCE_PARAM]: input.nonce,
+ });
+ return {
+ kind: 'redeem',
+ location: `http://127.0.0.1:${input.port}${REDEEM_PATH}?${params.toString()}`,
+ };
+}
diff --git a/packages/app/src/components/ShareReceiveDialog.dom.test.tsx b/packages/app/src/components/ShareReceiveDialog.dom.test.tsx
index 92b2cdc51..4aa1d869a 100644
--- a/packages/app/src/components/ShareReceiveDialog.dom.test.tsx
+++ b/packages/app/src/components/ShareReceiveDialog.dom.test.tsx
@@ -184,6 +184,26 @@ describe('ShareReceiveDialog runtime behavior', () => {
expect(typeof mod.ShareReceiveDialog).toBe('function');
});
+ test('clone failure leaves the dialog mounted and the sign-in affordance visible', async () => {
+ const cloneController = {
+ getAuthStatus: mock(() => Promise.resolve({ authenticated: false, host: 'github.com' })),
+ runClone: mock(() => Promise.resolve({ kind: 'error' })),
+ startSignIn: mock(() => Promise.resolve(null)),
+ };
+
+ await renderDialog({ cloneController });
+
+ await waitFor(() =>
+ expect((screen.getByTestId('share-receive-clone') as HTMLButtonElement).disabled).toBe(false),
+ );
+
+ fireEvent.click(screen.getByTestId('share-receive-clone'));
+ await waitFor(() => expect(cloneController.runClone).toHaveBeenCalled());
+
+ expect(screen.getByTestId('share-receive-dialog')).toBeTruthy();
+ expect(screen.getByTestId('share-receive-signin')).toBeTruthy();
+ });
+
test('non-ok payloads toast and dismiss without mounting the dialog', async () => {
const store = createTestStore({ kind: 'invalid' });
await renderDialog({ store });
@@ -193,7 +213,7 @@ describe('ShareReceiveDialog runtime behavior', () => {
expect(screen.queryByTestId('share-receive-dialog')).toBeNull();
});
- test('Q2 miss renders metadata, auth-gated clone, sign-in, clone success, and local picker recovery', async () => {
+ test('Q2 miss renders metadata, anonymous clone without sign-in, sign-in affordance, clone success, and local picker recovery', async () => {
const bridge = createBridge();
const store = createTestStore(okPayload({ branch: 'feat/share' }));
const cloneController = {
@@ -218,13 +238,12 @@ describe('ShareReceiveDialog runtime behavior', () => {
expect(screen.getByTestId('share-receive-metadata').textContent).toContain('docs/guide.md');
expect(screen.getByTestId('share-receive-metadata-branch').textContent).toBe('feat/share');
await waitFor(() =>
- expect(screen.getByTestId('share-receive-clone').textContent).toContain('Connect to clone'),
+ expect(screen.getByTestId('share-receive-clone').textContent).toContain(
+ 'Clone to a new folder',
+ ),
);
- expect((screen.getByTestId('share-receive-clone') as HTMLButtonElement).disabled).toBe(true);
-
- fireEvent.click(await screen.findByTestId('share-receive-signin'));
- await waitFor(() => expect(cloneController.startSignIn).toHaveBeenCalledTimes(1));
- expect(await screen.findByText(/@alice/)).toBeTruthy();
+ expect((screen.getByTestId('share-receive-clone') as HTMLButtonElement).disabled).toBe(false);
+ expect(await screen.findByTestId('share-receive-signin')).toBeTruthy();
fireEvent.click(screen.getByTestId('share-receive-clone'));
await waitFor(() =>
diff --git a/packages/app/src/components/ShareReceiveDialog.tsx b/packages/app/src/components/ShareReceiveDialog.tsx
index 2490576bf..4c65248d3 100644
--- a/packages/app/src/components/ShareReceiveDialog.tsx
+++ b/packages/app/src/components/ShareReceiveDialog.tsx
@@ -191,7 +191,7 @@ function ShareReceiveDialogInner({
});
return;
}
- if (!authStatus?.authenticated || cloneRunning) return;
+ if (cloneRunning) return;
setCloneRunning(true);
const cloneUrl = buildCloneUrl(expected);
let result: ShareReceiveCloneResult;
@@ -452,13 +452,8 @@ function ShareReceiveDialogInner({
if (!launcherMiss || !share || !expected) return null;
- const cloneEnabled =
- cloneController !== undefined && authStatus?.authenticated === true && !cloneRunning;
- const cloneLabel = cloneRunning
- ? t`Cloning...`
- : cloneController && authStatus?.authenticated === false
- ? t`Connect to clone`
- : t`Clone to a new folder`;
+ const cloneEnabled = cloneController !== undefined && !cloneRunning;
+ const cloneLabel = cloneRunning ? t`Cloning...` : t`Clone to a new folder`;
const shareOwner = share.owner;
const shareRepo = share.repo;
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index b99a75698..f192ffdb0 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -1273,7 +1273,6 @@
"gljvbT": [["words", "plural", { "one": ["word"], "other": ["words"] }]],
"gmJ0An": ["Failed to open folder."],
"goO4Ll": ["Editor status bar"],
- "gowVRq": ["Connect to clone"],
"gp3I7-": ["Before syncing, set your identity for git commits:"],
"gsePqm": ["Save Version"],
"gtEbeW": ["Highlight"],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index e01ace5e9..c6f57fd41 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -1251,10 +1251,6 @@ msgstr "Connect Open Knowledge to other tools you use."
msgid "Connect to AI tools"
msgstr "Connect to AI tools"
-#: src/components/ShareReceiveDialog.tsx
-msgid "Connect to clone"
-msgstr "Connect to clone"
-
#: src/components/settings/SettingsDialogBody.tsx
msgid "Connect to GitHub"
msgstr "Connect to GitHub"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 350724e74..1ff1ccabd 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -1273,7 +1273,6 @@
"gljvbT": [["words", "plural", { "one": ["ŵōŕď"], "other": ["ŵōŕďś"] }]],
"gmJ0An": ["Ƒàĩĺēď ţō ōƥēń ƒōĺďēŕ."],
"goO4Ll": ["Ēďĩţōŕ śţàţũś ƀàŕ"],
- "gowVRq": ["Ćōńńēćţ ţō ćĺōńē"],
"gp3I7-": ["ßēƒōŕē śŷńćĩńĝ, śēţ ŷōũŕ ĩďēńţĩţŷ ƒōŕ ĝĩţ ćōḿḿĩţś:"],
"gsePqm": ["Śàvē Vēŕśĩōń"],
"gtEbeW": ["Ĥĩĝĥĺĩĝĥţ"],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 089ed45dd..5c0b899ae 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -1246,10 +1246,6 @@ msgstr ""
msgid "Connect to AI tools"
msgstr ""
-#: src/components/ShareReceiveDialog.tsx
-msgid "Connect to clone"
-msgstr ""
-
#: src/components/settings/SettingsDialogBody.tsx
msgid "Connect to GitHub"
msgstr ""
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 8b7ad5f6f..a71400fb8 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -9,6 +9,7 @@ import {
realpathSync,
writeFileSync,
} from 'node:fs';
+import { createServer as createHttpServer } from 'node:http';
import { homedir as osHomedir, hostname as osHostname } from 'node:os';
import { basename, dirname, join } from 'node:path';
import {
@@ -165,6 +166,7 @@ import { runOkInit } from './ok-init.ts';
import {
type OnboardingFlowKind,
recordCreateNewBannerShown,
+ recordFirstRunShareHandoff,
recordOnboardingFlow,
} from './onboarding-telemetry.ts';
import { type EnsureCliOnPathResult, ensureCliOnPath } from './path-install.ts';
@@ -184,6 +186,7 @@ import { removeGitFolder } from './remove-git-folder.ts';
import { attachRendererConsoleCapture } from './renderer-console-capture.ts';
import { resolveDetachedSpawnArgs } from './resolve-detached-spawn-args.ts';
import { resolveShareTarget as resolveShareTargetMain } from './resolve-share-target.ts';
+import { startFirstRunHandshake } from './share-handoff.ts';
import { handleShellOpenExternal } from './shell-allowlist.ts';
import { createShowGateRegistry, type ShowGateRegistry } from './show-gate.ts';
import { reclaimProjectSkillsOnProjectOpen, reclaimUserSkillsOnLaunch } from './skill-reclaim.ts';
@@ -2346,6 +2349,8 @@ function bootPrimaryInstance(): void {
.then(async () => {
app.setAboutPanelOptions(buildAboutPanelOptions(app.getVersion()));
+ const isTrueFirstRun = !existsSync(join(app.getPath('userData'), 'state.json'));
+
const result = await runBootstrap({
loadAppState,
evaluateSchemaCompatibility,
@@ -2457,6 +2462,40 @@ function bootPrimaryInstance(): void {
protocolControl.drainQueuedUrls();
}
+ if (isTrueFirstRun && decision.action === 'navigator') {
+ startFirstRunHandshake({
+ isFirstRun: () => true,
+ createServer: (handler) => {
+ const httpServer = createHttpServer((req, res) => handler(req, res));
+ return {
+ listen: (port, host, cb) => {
+ httpServer.listen(port, host, cb);
+ },
+ on: (event, cb) => {
+ httpServer.on(event, cb);
+ },
+ address: () => httpServer.address(),
+ close: () => {
+ httpServer.close();
+ },
+ };
+ },
+ openExternal: (url) => {
+ void shell.openExternal(url).catch((err) => {
+ console.warn('[main] deferred-share openExternal failed', {
+ err: err instanceof Error ? err.message : String(err),
+ });
+ });
+ },
+ routeShareUrl: (url) => protocolControl.routeUrl(url),
+ recordOutcome: (outcome) => recordFirstRunShareHandoff(outcome),
+ log: {
+ warn: (obj, msg) => console.warn(msg, obj),
+ info: (obj, msg) => console.info(msg, obj),
+ },
+ });
+ }
+
void reclaimUserSkillsOnLaunch({
home: osHomedir(),
isPackaged: app.isPackaged,
diff --git a/packages/desktop/src/main/onboarding-telemetry.ts b/packages/desktop/src/main/onboarding-telemetry.ts
index 96fd8db23..1a2575a29 100644
--- a/packages/desktop/src/main/onboarding-telemetry.ts
+++ b/packages/desktop/src/main/onboarding-telemetry.ts
@@ -1,6 +1,7 @@
import type { CreateNewBannerKind } from '@inkeep/open-knowledge-core';
import { withSpanSync } from '@inkeep/open-knowledge-server';
import type { EntryPoint } from '../shared/entry-point.ts';
+import type { HandoffOutcome } from './share-handoff.ts';
export type OnboardingFlowKind =
| 'managed-promote'
@@ -41,6 +42,20 @@ export function recordCreateNewBannerShown(banner: CreateNewBannerKind): void {
);
}
+export type FirstRunHandoffOutcome = HandoffOutcome;
+
+export function recordFirstRunShareHandoff(outcome: FirstRunHandoffOutcome): void {
+ withSpanSync(
+ 'ok.desktop.firstRunShareHandoff',
+ {
+ attributes: {
+ 'ok.desktop.handoff_outcome': outcome,
+ },
+ },
+ () => undefined,
+ );
+}
+
export function recordOnboardingFlow(attrs: OnboardingTelemetryAttributes): void {
withSpanSync(
'ok.desktop.onboardingConsent',
diff --git a/packages/desktop/src/main/share-handoff.test.ts b/packages/desktop/src/main/share-handoff.test.ts
new file mode 100644
index 000000000..e3e17d851
--- /dev/null
+++ b/packages/desktop/src/main/share-handoff.test.ts
@@ -0,0 +1,325 @@
+import { describe, expect, test } from 'bun:test';
+import {
+ buildContinueUrl,
+ classifyRedeemRequest,
+ type FirstRunHandshakeDeps,
+ generateNonce,
+ type HandoffHttpRequest,
+ type HandoffHttpResponse,
+ type HandoffHttpServer,
+ type HandoffOutcome,
+ nonceMatches,
+ parseRedeemRequestUrl,
+ resolveContinueBase,
+ startFirstRunHandshake,
+} from './share-handoff.ts';
+
+const NONCE = 'a1b2c3d4e5f60718293a4b5c6d7e8f90';
+const TOKEN = 'AWh0dHBzOi8vZ2l0aHViLmNvbS9pbmtlZXAvdGVjaC1pcG9z';
+
+describe('nonce', () => {
+ test('generateNonce returns 128 bits of hex (32 chars)', () => {
+ const n = generateNonce();
+ expect(n).toMatch(/^[a-f0-9]{32}$/);
+ expect(generateNonce()).not.toBe(n);
+ });
+
+ test('nonceMatches is exact and false on null/length/value mismatch', () => {
+ expect(nonceMatches(NONCE, NONCE)).toBe(true);
+ expect(nonceMatches(NONCE, null)).toBe(false);
+ expect(nonceMatches(NONCE, `${NONCE}0`)).toBe(false);
+ expect(nonceMatches(NONCE, NONCE.replace('a', 'b'))).toBe(false);
+ });
+});
+
+describe('classifyRedeemRequest', () => {
+ test('non-redeem path is ignored (does not burn the nonce)', () => {
+ expect(
+ classifyRedeemRequest({
+ pathname: '/favicon.ico',
+ token: TOKEN,
+ nonce: NONCE,
+ expectedNonce: NONCE,
+ }),
+ ).toEqual({ kind: 'ignore' });
+ });
+
+ test('wrong nonce is invalid', () => {
+ expect(
+ classifyRedeemRequest({
+ pathname: '/redeem',
+ token: TOKEN,
+ nonce: 'deadbeef',
+ expectedNonce: NONCE,
+ }),
+ ).toEqual({ kind: 'invalid' });
+ });
+
+ test('malformed token is invalid', () => {
+ expect(
+ classifyRedeemRequest({
+ pathname: '/redeem',
+ token: 'has spaces!',
+ nonce: NONCE,
+ expectedNonce: NONCE,
+ }),
+ ).toEqual({ kind: 'invalid' });
+ });
+
+ test('valid request reconstructs the universal-link share URL + done hop', () => {
+ const decision = classifyRedeemRequest({
+ pathname: '/redeem',
+ token: TOKEN,
+ nonce: NONCE,
+ expectedNonce: NONCE,
+ });
+ expect(decision).toEqual({
+ kind: 'redeem',
+ shareUrl: `https://openknowledge.ai/d/${TOKEN}`,
+ doneLocation: 'https://openknowledge.ai/continue/done',
+ });
+ });
+});
+
+describe('resolveContinueBase (dev override, loopback-pinned)', () => {
+ test('defaults to production when the env var is unset', () => {
+ expect(resolveContinueBase({})).toBe('https://openknowledge.ai');
+ });
+
+ test.each([
+ ['http://localhost:3010', 'http://localhost:3010'],
+ ['http://127.0.0.1:3010/', 'http://127.0.0.1:3010'],
+ ['https://localhost:3010', 'https://localhost:3010'],
+ ['http://[::1]:3010', 'http://[::1]:3010'],
+ ])('honors a loopback override %s → %s (trailing slash trimmed)', (input, expected) => {
+ expect(resolveContinueBase({ OK_CONTINUE_URL_BASE: input })).toBe(expected);
+ });
+
+ test.each([
+ ['https://evil.example.com'],
+ ['http://192.168.1.5:3010'],
+ ['http://openknowledge.ai.evil.com'],
+ ['ftp://localhost'],
+ ['not a url'],
+ [''],
+ ])('rejects non-loopback / malformed %s → falls back to production', (input) => {
+ expect(resolveContinueBase({ OK_CONTINUE_URL_BASE: input })).toBe('https://openknowledge.ai');
+ });
+});
+
+describe('url helpers', () => {
+ test('buildContinueUrl targets the apex continue route with port+nonce', () => {
+ expect(buildContinueUrl(52431, NONCE, 'https://openknowledge.ai')).toBe(
+ `https://openknowledge.ai/continue?port=52431&nonce=${NONCE}`,
+ );
+ });
+
+ test('buildContinueUrl honors a loopback base for local testing', () => {
+ expect(buildContinueUrl(52431, NONCE, 'http://localhost:3010')).toBe(
+ `http://localhost:3010/continue?port=52431&nonce=${NONCE}`,
+ );
+ });
+
+ test('classifyRedeemRequest done hop follows the continue base; share URL stays on apex', () => {
+ const decision = classifyRedeemRequest({
+ pathname: '/redeem',
+ token: TOKEN,
+ nonce: NONCE,
+ expectedNonce: NONCE,
+ continueBase: 'http://localhost:3010',
+ });
+ expect(decision).toEqual({
+ kind: 'redeem',
+ shareUrl: `https://openknowledge.ai/d/${TOKEN}`,
+ doneLocation: 'http://localhost:3010/continue/done',
+ });
+ });
+
+ test('parseRedeemRequestUrl pulls token + nonce from the query', () => {
+ const parsed = parseRedeemRequestUrl(
+ `/redeem?token=${TOKEN}&nonce=${NONCE}`,
+ 'http://127.0.0.1',
+ );
+ expect(parsed).toEqual({ pathname: '/redeem', token: TOKEN, nonce: NONCE });
+ });
+});
+
+class FakeResponse implements HandoffHttpResponse {
+ statusCode = 200;
+ headers: Record<string, string> = {};
+ body: string | undefined;
+ ended = false;
+ setHeader(name: string, value: string) {
+ this.headers[name] = value;
+ }
+ end(body?: string) {
+ this.body = body;
+ this.ended = true;
+ }
+}
+
+class FakeServer implements HandoffHttpServer {
+ handler: (req: HandoffHttpRequest, res: HandoffHttpResponse) => void;
+ errorCb: ((err: NodeJS.ErrnoException) => void) | null = null;
+ closed = false;
+ listening = false;
+ constructor(handler: (req: HandoffHttpRequest, res: HandoffHttpResponse) => void) {
+ this.handler = handler;
+ }
+ listen(_port: number, _host: string, cb: () => void) {
+ this.listening = true;
+ cb();
+ }
+ on(_event: 'error', cb: (err: NodeJS.ErrnoException) => void) {
+ this.errorCb = cb;
+ }
+ address() {
+ return { port: 52431 };
+ }
+ close() {
+ this.closed = true;
+ }
+ request(url: string): FakeResponse {
+ const res = new FakeResponse();
+ this.handler({ url }, res);
+ return res;
+ }
+}
+
+function harness(over: Partial<FirstRunHandshakeDeps> = {}) {
+ const outcomes: HandoffOutcome[] = [];
+ const opened: string[] = [];
+ const routed: string[] = [];
+ let server: FakeServer | undefined;
+ const deps: FirstRunHandshakeDeps = {
+ isFirstRun: () => true,
+ createServer: (handler) => {
+ server = new FakeServer(handler);
+ return server;
+ },
+ openExternal: (url) => opened.push(url),
+ routeShareUrl: (url) => routed.push(url),
+ recordOutcome: (o) => outcomes.push(o),
+ generateNonce: () => NONCE,
+ setTimeout: () => 0,
+ clearTimeout: () => undefined,
+ ...over,
+ };
+ startFirstRunHandshake(deps);
+ const getServer = (): FakeServer => {
+ if (!server) throw new Error('handshake did not create a server');
+ return server;
+ };
+ return { outcomes, opened, routed, getServer };
+}
+
+describe('startFirstRunHandshake', () => {
+ test('not a first run → records skipped, opens nothing', () => {
+ const h = harness({ isFirstRun: () => false });
+ expect(h.outcomes).toEqual(['skipped']);
+ expect(h.opened).toEqual([]);
+ });
+
+ test('arms a loopback listener and opens the continue URL with the nonce', () => {
+ const h = harness();
+ expect(h.opened).toEqual([`https://openknowledge.ai/continue?port=52431&nonce=${NONCE}`]);
+ expect(h.outcomes).toEqual([]);
+ });
+
+ test('valid redemption routes the share URL, 302s to done, records redeemed', () => {
+ const h = harness();
+ const res = h.getServer().request(`/redeem?token=${TOKEN}&nonce=${NONCE}`);
+ expect(res.statusCode).toBe(302);
+ expect(res.headers.Location).toBe('https://openknowledge.ai/continue/done');
+ expect(h.routed).toEqual([`https://openknowledge.ai/d/${TOKEN}`]);
+ expect(h.outcomes).toEqual(['redeemed']);
+ expect(h.getServer().closed).toBe(true);
+ });
+
+ test('wrong nonce → invalid, no routing, friendly failure body', () => {
+ const h = harness();
+ const res = h.getServer().request(`/redeem?token=${TOKEN}&nonce=deadbeef`);
+ expect(res.statusCode).toBe(400);
+ expect(h.routed).toEqual([]);
+ expect(h.outcomes).toEqual(['invalid']);
+ });
+
+ test('nonce is single-use: a second request after redemption gets 410', () => {
+ const h = harness();
+ const server = h.getServer();
+ server.request(`/redeem?token=${TOKEN}&nonce=${NONCE}`);
+ const second = server.request(`/redeem?token=${TOKEN}&nonce=${NONCE}`);
+ expect(second.statusCode).toBe(410);
+ expect(h.routed).toHaveLength(1);
+ });
+
+ test('non-redeem probe does not burn the nonce', () => {
+ const h = harness();
+ const server = h.getServer();
+ const probe = server.request('/favicon.ico');
+ expect(probe.statusCode).toBe(404);
+ const res = server.request(`/redeem?token=${TOKEN}&nonce=${NONCE}`);
+ expect(res.statusCode).toBe(302);
+ expect(h.outcomes).toEqual(['redeemed']);
+ });
+
+ test('timeout closes the listener and records timeout', () => {
+ let fire: (() => void) | null = null;
+ const h = harness({
+ setTimeout: (cb) => {
+ fire = cb;
+ return 0;
+ },
+ });
+ if (!fire) throw new Error('timeout was not scheduled');
+ fire();
+ expect(h.outcomes).toEqual(['timeout']);
+ expect(h.getServer().closed).toBe(true);
+ });
+
+ test('server error event records bind-failed; a second error does not double-record', () => {
+ const h = harness();
+ const server = h.getServer();
+ server.errorCb?.({
+ code: 'EADDRINUSE',
+ name: 'Error',
+ message: 'bind error',
+ } as NodeJS.ErrnoException);
+ expect(h.outcomes).toEqual(['bind-failed']);
+ server.errorCb?.({
+ code: 'EADDRINUSE',
+ name: 'Error',
+ message: 'bind error',
+ } as NodeJS.ErrnoException);
+ expect(h.outcomes).toHaveLength(1);
+ });
+
+ test('address() returning null in the listen callback records bind-failed and closes', () => {
+ let closed = false;
+ const h = harness({
+ createServer: (_handler) => ({
+ listen(_port: number, _host: string, cb: () => void) {
+ cb();
+ },
+ on(_event: 'error', _cb: (err: NodeJS.ErrnoException) => void) {},
+ address: () => null,
+ close: () => {
+ closed = true;
+ },
+ }),
+ });
+ expect(h.outcomes).toEqual(['bind-failed']);
+ expect(closed).toBe(true);
+ });
+
+ test('routeShareUrl throwing after response does not propagate — records redeemed', () => {
+ const h = harness({
+ routeShareUrl: () => {
+ throw new Error('downstream error');
+ },
+ });
+ const res = h.getServer().request(`/redeem?token=${TOKEN}&nonce=${NONCE}`);
+ expect(res.statusCode).toBe(302);
+ expect(h.outcomes).toEqual(['redeemed']);
+ });
+});
diff --git a/packages/desktop/src/main/share-handoff.ts b/packages/desktop/src/main/share-handoff.ts
new file mode 100644
index 000000000..71855383b
--- /dev/null
+++ b/packages/desktop/src/main/share-handoff.ts
@@ -0,0 +1,221 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+const PROD_BASE = 'https://openknowledge.ai';
+const REDEEM_PATH = '/redeem';
+const REDEEM_TOKEN_PARAM = 'token';
+const REDEEM_NONCE_PARAM = 'nonce';
+
+const SHARE_LINK_PREFIX = `${PROD_BASE}/d/`;
+
+export function resolveContinueBase(env: Record<string, string | undefined> = process.env): string {
+ const override = env.OK_CONTINUE_URL_BASE?.trim();
+ if (override && isLoopbackHttpUrl(override)) return override.replace(/\/+$/, '');
+ return PROD_BASE;
+}
+
+function isLoopbackHttpUrl(value: string): boolean {
+ let url: URL;
+ try {
+ url = new URL(value);
+ } catch {
+ return false;
+ }
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
+ const host = url.hostname;
+ return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
+const MAX_TOKEN_LENGTH = 4096;
+const TOKEN_RE = /^[A-Za-z0-9_-]+$/;
+
+const NONCE_BYTES = 16;
+
+const DEFAULT_LISTENER_LIFETIME_MS = 3 * 60 * 1000;
+
+export function generateNonce(): string {
+ return randomBytes(NONCE_BYTES).toString('hex');
+}
+
+export function nonceMatches(expected: string, candidate: string | null): boolean {
+ if (candidate === null) return false;
+ const a = Buffer.from(expected, 'utf8');
+ const b = Buffer.from(candidate, 'utf8');
+ if (a.length !== b.length) return false;
+ return timingSafeEqual(a, b);
+}
+
+function isValidToken(token: string | null): token is string {
+ return (
+ token !== null && token.length > 0 && token.length <= MAX_TOKEN_LENGTH && TOKEN_RE.test(token)
+ );
+}
+
+export function buildContinueUrl(
+ port: number,
+ nonce: string,
+ base: string = resolveContinueBase(),
+): string {
+ const params = new URLSearchParams({ port: String(port), nonce });
+ return `${base}/continue?${params.toString()}`;
+}
+
+export type RedeemDecision =
+ | { kind: 'redeem'; shareUrl: string; doneLocation: string }
+ | { kind: 'invalid' }
+ | { kind: 'ignore' };
+
+export function classifyRedeemRequest(input: {
+ pathname: string;
+ token: string | null;
+ nonce: string | null;
+ expectedNonce: string;
+ continueBase?: string;
+}): RedeemDecision {
+ if (input.pathname !== REDEEM_PATH) return { kind: 'ignore' };
+ if (!nonceMatches(input.expectedNonce, input.nonce)) return { kind: 'invalid' };
+ if (!isValidToken(input.token)) return { kind: 'invalid' };
+ return {
+ kind: 'redeem',
+ shareUrl: `${SHARE_LINK_PREFIX}${input.token}`,
+ doneLocation: `${input.continueBase ?? PROD_BASE}/continue/done`,
+ };
+}
+
+export function parseRedeemRequestUrl(
+ requestUrl: string,
+ base: string,
+): { pathname: string; token: string | null; nonce: string | null } {
+ const url = new URL(requestUrl, base);
+ return {
+ pathname: url.pathname,
+ token: url.searchParams.get(REDEEM_TOKEN_PARAM),
+ nonce: url.searchParams.get(REDEEM_NONCE_PARAM),
+ };
+}
+
+export interface HandoffHttpResponse {
+ statusCode: number;
+ setHeader(name: string, value: string): void;
+ end(body?: string): void;
+}
+export interface HandoffHttpRequest {
+ url?: string;
+}
+export interface HandoffHttpServer {
+ listen(port: number, host: string, cb: () => void): void;
+ on(event: 'error', cb: (err: NodeJS.ErrnoException) => void): void;
+ address(): { port: number } | string | null;
+ close(): void;
+}
+
+export interface FirstRunHandshakeDeps {
+ isFirstRun: () => boolean;
+ createServer: (
+ handler: (req: HandoffHttpRequest, res: HandoffHttpResponse) => void,
+ ) => HandoffHttpServer;
+ openExternal: (url: string) => void;
+ routeShareUrl: (url: string) => void;
+ recordOutcome: (outcome: HandoffOutcome) => void;
+ continueBase?: string;
+ generateNonce?: () => string;
+ setTimeout?: (cb: () => void, ms: number) => unknown;
+ clearTimeout?: (handle: unknown) => void;
+ listenerLifetimeMs?: number;
+ log?: { warn(obj: object, msg: string): void; info?(obj: object, msg: string): void };
+}
+
+export type HandoffOutcome = 'redeemed' | 'invalid' | 'timeout' | 'skipped' | 'bind-failed';
+
+export function startFirstRunHandshake(deps: FirstRunHandshakeDeps): void {
+ if (!deps.isFirstRun()) {
+ deps.recordOutcome('skipped');
+ return;
+ }
+
+ const mkNonce = deps.generateNonce ?? generateNonce;
+ const schedule = deps.setTimeout ?? ((cb, ms) => setTimeout(cb, ms));
+ const cancel = deps.clearTimeout ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+ const lifetime = deps.listenerLifetimeMs ?? DEFAULT_LISTENER_LIFETIME_MS;
+ const continueBase = deps.continueBase ?? resolveContinueBase();
+
+ const nonce = mkNonce();
+ let settled = false;
+ let timer: unknown = null;
+
+ const server = deps.createServer((req, res) => {
+ if (settled) {
+ res.statusCode = 410;
+ res.end('Gone');
+ return;
+ }
+
+ let decision: RedeemDecision;
+ try {
+ const parsed = parseRedeemRequestUrl(req.url ?? '/', 'http://127.0.0.1');
+ decision = classifyRedeemRequest({ ...parsed, expectedNonce: nonce, continueBase });
+ } catch {
+ decision = { kind: 'invalid' };
+ }
+
+ if (decision.kind === 'ignore') {
+ res.statusCode = 404;
+ res.end('Not found');
+ return;
+ }
+
+ settled = true;
+ if (timer !== null) cancel(timer);
+
+ if (decision.kind === 'redeem') {
+ res.statusCode = 302;
+ res.setHeader('Location', decision.doneLocation);
+ res.end();
+ deps.log?.info?.({}, '[receive] source=deferred action=redeemed');
+ deps.recordOutcome('redeemed');
+ try {
+ deps.routeShareUrl(decision.shareUrl);
+ } catch (err) {
+ deps.log?.warn(
+ { err: err instanceof Error ? err.message : String(err) },
+ '[receive] source=deferred routeShareUrl threw',
+ );
+ }
+ } else {
+ res.statusCode = 400;
+ res.setHeader('content-type', 'text/plain; charset=utf-8');
+ res.end(
+ 'This share handoff could not be completed. Open the original share link again to try once more.',
+ );
+ deps.log?.warn({}, '[receive] source=deferred action=invalid');
+ deps.recordOutcome('invalid');
+ }
+ server.close();
+ });
+
+ server.on('error', (err) => {
+ deps.log?.warn({ code: err.code }, '[receive] source=deferred listener error');
+ if (!settled) {
+ settled = true;
+ if (timer !== null) cancel(timer);
+ deps.recordOutcome('bind-failed');
+ }
+ });
+
+ server.listen(0, '127.0.0.1', () => {
+ const addr = server.address();
+ if (addr === null || typeof addr === 'string') {
+ settled = true;
+ deps.recordOutcome('bind-failed');
+ server.close();
+ return;
+ }
+ deps.openExternal(buildContinueUrl(addr.port, nonce, continueBase));
+ timer = schedule(() => {
+ if (settled) return;
+ settled = true;
+ deps.log?.info?.({}, '[receive] source=deferred action=timeout');
+ deps.recordOutcome('timeout');
+ server.close();
+ }, lifetime);
+ });
+}
diff --git a/packages/desktop/src/main/url-scheme.ts b/packages/desktop/src/main/url-scheme.ts
index 4b698ae01..6ae960579 100644
--- a/packages/desktop/src/main/url-scheme.ts
+++ b/packages/desktop/src/main/url-scheme.ts
@@ -336,6 +336,7 @@ interface ProtocolHandlerDeps {
getAnyReadyWindow(): BrowserWindowHandle | null;
getInitialArgv?: () => readonly string[];
setTimeout?: (cb: () => void, ms: number) => unknown;
+ now?: () => number;
log?: {
warn(obj: object, msg: string): void;
info?(obj: object, msg: string): void;
@@ -348,14 +349,18 @@ interface BrowserWindowHandle {}
interface ProtocolHandlerControl {
singleFileLaunch(): boolean;
drainQueuedUrls(): void;
+ routeUrl(url: string): void;
}
+const SHARE_DEDUP_WINDOW_MS = 10_000;
+
const QUEUE_FLUSH_MAX_ATTEMPTS = 10;
const QUEUE_FLUSH_INTERVAL_MS = 500;
export function registerProtocolHandler(deps: ProtocolHandlerDeps): ProtocolHandlerControl {
const schedule = deps.setTimeout ?? ((cb, ms) => setTimeout(cb, ms));
const urlQueue: string[] = [];
+ const shareDedup = new Map<string, number>();
let flushed = false;
let singleFileLaunch = false;
@@ -564,6 +569,16 @@ export function registerProtocolHandler(deps: ProtocolHandlerDeps): ProtocolHand
broadcastShareToast(url, { kind: result.kind });
return;
}
+ const now = deps.now ? deps.now() : Date.now();
+ const last = shareDedup.get(result.payload.sharedUrl);
+ if (last !== undefined && now - last < SHARE_DEDUP_WINDOW_MS) {
+ deps.log?.warn({ source: result.source, result: result.kind }, '[receive] action=deduped');
+ return;
+ }
+ shareDedup.set(result.payload.sharedUrl, now);
+ for (const [url, ts] of shareDedup) {
+ if (now - ts >= SHARE_DEDUP_WINDOW_MS) shareDedup.delete(url);
+ }
const resolver = deps.resolveShareTarget;
if (!resolver) {
deps.log?.warn({ url }, '[receive] resolveShareTarget dep missing — share dropped');
@@ -719,5 +734,6 @@ export function registerProtocolHandler(deps: ProtocolHandlerDeps): ProtocolHand
return {
singleFileLaunch: () => singleFileLaunch,
drainQueuedUrls: () => drainAll(),
+ routeUrl: (url) => enqueueOrRoute(url),
};
}
diff --git a/packages/desktop/tests/main/url-scheme-handler.test.ts b/packages/desktop/tests/main/url-scheme-handler.test.ts
index 2ea9c1d18..d7d83005b 100644
--- a/packages/desktop/tests/main/url-scheme-handler.test.ts
+++ b/packages/desktop/tests/main/url-scheme-handler.test.ts
@@ -259,6 +259,59 @@ describe('registerProtocolHandler — before-quit Launch Services cleanup', () =
});
});
+describe('registerProtocolHandler — deferred-share routeUrl + dedup', () => {
+ let env: TestEnv;
+
+ beforeEach(() => {
+ env = makeEnv();
+ });
+
+ test('routeUrl feeds a redeemed /d/ universal link through the share spine; a near-simultaneous duplicate is deduped', async () => {
+ env.readyWindow = { id: 'pre-existing' };
+ const resolveShareTarget = mock(async (): Promise<CandidateSelection> => ({ kind: 'miss' }));
+ const routeShareToNavigator = mock(() => {});
+ let clock = 1_000_000;
+
+ const control = registerProtocolHandler({
+ app: env.app,
+ focusWindowForProject: env.focusWindowForProject,
+ openProject: env.openProject,
+ sendDeepLink: env.sendDeepLink,
+ getAnyReadyWindow: env.getAnyReadyWindow,
+ resolveShareTarget: resolveShareTarget as unknown as (
+ share: ShareUrlPayload,
+ ) => Promise<CandidateSelection>,
+ routeShareToNavigator,
+ setTimeout: (cb, ms) => env.timers.push({ cb, ms }),
+ now: () => clock,
+ });
+ env.app.resolveReady();
+ await flushPromises();
+
+ const token = encodeShareUrl('https://github.com/inkeep/tech-ipos/blob/main/README.md');
+ const url = `https://openknowledge.ai/d/${token}`;
+
+ control.routeUrl(url);
+ await flushPromises();
+ await flushPromises();
+ expect(resolveShareTarget).toHaveBeenCalledTimes(1);
+ expect(routeShareToNavigator).toHaveBeenCalledTimes(1); // miss → launcher-miss
+
+ clock += 2_000;
+ control.routeUrl(url);
+ await flushPromises();
+ await flushPromises();
+ expect(resolveShareTarget).toHaveBeenCalledTimes(1);
+ expect(routeShareToNavigator).toHaveBeenCalledTimes(1);
+
+ clock += 11_000;
+ control.routeUrl(url);
+ await flushPromises();
+ await flushPromises();
+ expect(resolveShareTarget).toHaveBeenCalledTimes(2);
+ });
+});
+
describe('registerProtocolHandler — queue-then-flush', () => {
let env: TestEnv;
diff --git a/packages/server/src/github-permissions.test.ts b/packages/server/src/github-permissions.test.ts
index fdb93b6f6..8536c9902 100644
--- a/packages/server/src/github-permissions.test.ts
+++ b/packages/server/src/github-permissions.test.ts
@@ -84,10 +84,10 @@ describe('checkPushPermission — classification', () => {
expected: { kind: 'denied', reason: 'no-collaborator' },
},
{
- name: '200 without permissions field (anonymous public repo) → unknown/malformed-response',
+ name: '200 without permissions field (authed, schema drift) → unknown/malformed-response',
status: 200,
body: { full_name: 'inkeep/open-knowledge' },
- withToken: false,
+ withToken: true,
expected: { kind: 'unknown', error: 'malformed-response' },
},
{
@@ -103,12 +103,6 @@ describe('checkPushPermission — classification', () => {
withToken: true,
expected: { kind: 'denied', reason: 'private-no-access' },
},
- {
- name: '404 anonymous → denied/repo-not-found',
- status: 404,
- withToken: false,
- expected: { kind: 'denied', reason: 'repo-not-found' },
- },
{
name: '401 → unknown/token-invalid',
status: 401,
@@ -198,7 +192,7 @@ describe('checkPushPermission — classification', () => {
const result = await checkPushPermission({
owner: 'inkeep',
repo: 'open-knowledge',
- detectGh: ghUnavailable(),
+ detectGh: ghAvailable(),
_fetchFn: fetchFn,
});
expect(result).toEqual({ kind: 'unknown', error: 'network' });
@@ -219,7 +213,7 @@ describe('checkPushPermission — classification', () => {
const result = await checkPushPermission({
owner: 'inkeep',
repo: 'open-knowledge',
- detectGh: ghUnavailable(),
+ detectGh: ghAvailable(),
_fetchFn: fetchFn,
_timeoutMs: 20,
});
@@ -257,23 +251,29 @@ describe('checkPushPermission — token resolution', () => {
expect(hosts).toEqual(['github.com']);
});
- test('anonymous: no gh and no stored token → no Authorization header', async () => {
+ test('anonymous: no credential → denied/no-collaborator with NO HTTP call (short-circuit)', async () => {
const { fetch, calls } = mockFetch(() => jsonResponse(200, {}));
const { store } = fakeStore(null);
- await checkPushPermission({
+ const result = await checkPushPermission({
owner: 'inkeep',
repo: 'open-knowledge',
detectGh: ghUnavailable(),
tokenStore: store,
_fetchFn: fetch,
});
- expect(authHeader(calls[0]?.init)).toBeUndefined();
+ expect(result).toEqual({ kind: 'denied', reason: 'no-collaborator' });
+ expect(calls).toHaveLength(0); // no credential ⇒ no push ⇒ no probe
});
- test('anonymous: omitting both detectGh and tokenStore probes without auth', async () => {
+ test('anonymous: omitting both detectGh and tokenStore short-circuits without a request', async () => {
const { fetch, calls } = mockFetch(() => jsonResponse(200, {}));
- await checkPushPermission({ owner: 'inkeep', repo: 'open-knowledge', _fetchFn: fetch });
- expect(authHeader(calls[0]?.init)).toBeUndefined();
+ const result = await checkPushPermission({
+ owner: 'inkeep',
+ repo: 'open-knowledge',
+ _fetchFn: fetch,
+ });
+ expect(result).toEqual({ kind: 'denied', reason: 'no-collaborator' });
+ expect(calls).toHaveLength(0);
});
test('gh detection is scoped to the requested host', async () => {
@@ -316,7 +316,7 @@ describe('checkPushPermission — request shape', () => {
owner: 'acme',
repo: 'docs',
host: 'github.example.com',
- detectGh: ghUnavailable(),
+ detectGh: ghAvailable(),
_fetchFn: fetch,
});
expect(calls[0]?.url).toBe('https://github.example.com/api/v3/repos/acme/docs');
@@ -327,7 +327,7 @@ describe('checkPushPermission — request shape', () => {
await checkPushPermission({
owner: 'owner/../escape',
repo: 'name',
- detectGh: ghUnavailable(),
+ detectGh: ghAvailable(),
_fetchFn: fetch,
});
expect(calls[0]?.url).toBe('https://api.github.com/repos/owner%2F..%2Fescape/name');
diff --git a/packages/server/src/github-permissions.ts b/packages/server/src/github-permissions.ts
index 9dc7880d5..d8e7dae30 100644
--- a/packages/server/src/github-permissions.ts
+++ b/packages/server/src/github-permissions.ts
@@ -131,6 +131,12 @@ async function runProbe(opts: CheckPushPermissionOptions): Promise<PushPermissio
detectGh,
tokenStore,
);
+
+ if (tokenSource === 'anonymous') {
+ log.info({ host }, '[permissions] no credential resolved — denying push (read-only)');
+ return { kind: 'denied', reason: 'no-collaborator' };
+ }
+
const url = `${githubApiBase(host)}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
log.info(