API backends

Every FKN API is imported into browser code. Cloud, extension, and desktop describe where the work runs, not which client can call it. Cloud APIs are therefore available to browser apps with no extension installed.

import { 
const fetch: (input: RequestInfo | URL, init?: RequestInit & {
    reason?: string;
    render?: boolean;
}) => Promise<Response>
fetch, 
(alias) namespace cloud
import cloud
cloud, 
(alias) namespace extension
import extension
extension, 
(alias) namespace desktop
import desktop
desktop } from '@fkn/lib'

await 
function fetch(input: RequestInfo | URL, init?: RequestInit & {
    reason?: string;
    render?: boolean;
}): Promise<Response>
fetch('https://example.com')            // chooses extension or cloud
await 
(alias) namespace cloud
import cloud
cloud.
cloud_d_exports.fetch(input: string | Request | URL, init?: (RequestInit & {
    render?: boolean;
}) | undefined): Promise<Response>
export cloud_d_exports.fetch
fetch('https://example.com')      // always uses the FKN cloud proxy
await 
(alias) namespace extension
import extension
extension.
extension_d_exports.fetch(input: RequestInfo | URL, init?: extension.FetchInit): Promise<Response>
export extension_d_exports.fetch
fetch('https://example.com')  // always uses the browser extension
(alias) namespace desktop
import desktop
desktop.
desktop_d_exports.available(): boolean
export desktop_d_exports.available
Typed placeholder for the planned desktop backend. Always false in this release.
available()                           // false until the desktop backend ships

Current backends

Backend	Where the work runs	Current capabilities	Availability
`cloud.*`	FKN infrastructure	HTTP proxy, TCP/UDP, DNS, storage, quota, isolated or persistent frame sessions	Available to browser apps, no install
`extension.*`	The user’s browser	Cross-origin fetch, optional session cookies, browser-session frames, locators, cookies, request-header rules	Requires the FKN extension
`desktop.*`	The user’s machine	Typed placeholders for fetch, sockets, DNS, and storage	Planned; availability checks return false and operation calls throw

cloud.available() reports whether the current JavaScript realm has the FKN message transport. It is not a remote service health check. extension.available() is a point-in-time check and can change after the extension announces itself. desktop.available() is always false in @fkn/lib 0.6.1.

import { 
(alias) namespace cloud
import cloud
cloud, 
(alias) namespace extension
import extension
extension, 
(alias) namespace desktop
import desktop
desktop } from '@fkn/lib'

(alias) namespace cloud
import cloud
cloud.
cloud_d_exports.available(): boolean
export cloud_d_exports.available
available()
(alias) namespace extension
import extension
extension.
extension_d_exports.available(): boolean
export extension_d_exports.available
available()
(alias) namespace desktop
import desktop
desktop.
desktop_d_exports.available(): boolean
export desktop_d_exports.available
Typed placeholder for the planned desktop backend. Always false in this release.
available()

How root exports resolve

The root exports are conveniences, but they do not all use one generic fallback chain.

Root export	Current behavior
`fetch()`	Chooses the exposed extension first, then the future desktop backend, then cloud
`attachFrame()`	Uses the extension when exposed; degrades to the cloud render proxy otherwise
`net`, `dgram`, `http`, `dns`	Direct aliases of the cloud-backed implementations
`fs`	Hybrid storage: local OPFS first, with optional cloud replication for a connected account
`opfs`	Local browser storage only

`fetch()` chooses a backend

Bare cookieless fetch() prefers the extension when it is exposed. That extension operation is severity 0, so it is granted automatically rather than showing a prompt. Without the extension, the call uses the cloud proxy. Pick cloud.fetch() or extension.fetch() explicitly whenever the egress location matters to your app.

import { 
const fetch: (input: RequestInfo | URL, init?: RequestInit & {
    reason?: string;
    render?: boolean;
}) => Promise<Response>
fetch, 
(alias) namespace cloud
import cloud
cloud, 
(alias) namespace extension
import extension
extension } from '@fkn/lib'

await 
function fetch(input: RequestInfo | URL, init?: RequestInit & {
    reason?: string;
    render?: boolean;
}): Promise<Response>
fetch('https://example.com/public.json')
await 
(alias) namespace cloud
import cloud
cloud.
cloud_d_exports.fetch(input: string | Request | URL, init?: (RequestInit & {
    render?: boolean;
}) | undefined): Promise<Response>
export cloud_d_exports.fetch
fetch('https://example.com/public.json')
await 
(alias) namespace extension
import extension
extension.
extension_d_exports.fetch(input: RequestInfo | URL, init?: extension.FetchInit): Promise<Response>
export extension_d_exports.fetch
fetch('https://example.com/public.json')

A bare fetch is cookieless by default. Passing credentials: 'include' in the second argument always selects the extension because only that backend can use the target site’s browser session. If the extension is missing, the configured install flow runs and the call rejects rather than falling back to cloud. Credentials set only on a Request object are not used for backend selection in the current release.

import { 
const fetch: (input: RequestInfo | URL, init?: RequestInit & {
    reason?: string;
    render?: boolean;
}) => Promise<Response>
fetch } from '@fkn/lib'

const 
const response: Response
response = await 
function fetch(input: RequestInfo | URL, init?: RequestInit & {
    reason?: string;
    render?: boolean;
}): Promise<Response>
fetch('https://example.com/me', {
  
RequestInit.credentials?: RequestCredentials | undefined
A string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. Sets request's credentials.
credentials: 'include',
  
reason?: string | undefined
reason: 'Load the profile from your existing session',
})

`attachFrame()` has its own rule

Bare attachFrame() waits briefly for extension exposure and uses the extension when it shows up. When it does not, the call degrades to the cloud render proxy in every cookie mode with no install prompt: the default maps to the persistent cloud jar, and syncCookies: false to an isolated per-attach jar. The exceptions are lockdown: true and realms without a configured render proxy, which stay on the extension path and surface the install flow. See attachFrame().

Storage is separate

The root fs export combines browser OPFS with optional cloud replication. It is not selected through the networking backend chain. See Storage.

Target restrictions

Fetch APIs refuse FKN’s own domains (fkn.app, fkn.dev, and their subdomains). The same boundary is enforced in the library, broker, proxy, and extension so direct calls to a lower layer behave consistently.

Capability support

This table shows the execution backends for each browser-callable API. It does not show native web-platform support.

@fkn/lib capabilities by execution backend

All APIs below are called from browser code. The columns show which backend performs the work.

API / feature	Extension	Cloud	Desktop
`fetch`
`cross-origin`	Supported	Supported	Planned
`credentials: 'include'`Carries the browser session	Supported	Not available	Not available
`net (TCP)`	Not available	Supported	Planned
`dgram (UDP)`	Not available	Supported	Planned
`http`	Not available	Supported	Not available
`dns`	Not available	Supported	Not available
`File storage`Root fs also uses OPFS	Not available	Supported	Planned
`attachFrame / locators`Cloud: no lockdown or videoElement	Supported	Supported	Not available
`cookies.get`	Supported	Not available	Not available
`quota`	Not available	Supported	Not available