@abide/abide 0.57.1 → 0.100.0

package/src/server/nativeMenu.ts

@@ -0,0 +1,296 @@
+// THE DESKTOP APP'S MENU BAR (38.89): the default, with what the page the window shows exports,
+// built as an `NSMenu`.
+
+import { FFIType } from 'bun:ffi'
+import type { MenuRole } from '#shared/menuItem.ts'
+import {
+    definedClass,
+    type Id,
+    nsString,
+    objcClass,
+    selector,
+    send,
+    sendTyped,
+} from './appKit.ts'
+
+/**
+ * A menu item as the window builds it: the defaults, and what a page told it (`reportMenu`), each
+ * item the page answers numbered by `id`.
+ */
+export type NativeItem =
+    | 'separator'
+    | {
+          label: string
+          key?: string | undefined
+          role?: MenuRole | undefined
+          id?: number | undefined
+          items?: NativeItem[] | undefined
+      }
+
+// 38.90 — A ROLE AppKit ALREADY ANSWERS is sent down the responder chain, so `copy` copies whatever
+// holds the selection and is greyed where nothing does. The rest are the launcher's own.
+const RESPONDER_ROLES: Partial<Record<MenuRole, string>> = {
+    about: 'orderFrontStandardAboutPanel:',
+    hide: 'hide:',
+    hideOthers: 'hideOtherApplications:',
+    showAll: 'unhideAllApplications:',
+    quit: 'terminate:',
+    close: 'performClose:',
+    undo: 'undo:',
+    redo: 'redo:',
+    cut: 'cut:',
+    copy: 'copy:',
+    paste: 'paste:',
+    selectAll: 'selectAll:',
+    fullscreen: 'toggleFullScreen:',
+    minimize: 'performMiniaturize:',
+    zoom: 'performZoom:',
+    front: 'arrangeInFront:',
+}
+
+const MODIFIERS: Record<string, number> = {
+    shift: 1 << 17,
+    ctrl: 1 << 18,
+    control: 1 << 18,
+    alt: 1 << 19,
+    option: 1 << 19,
+    cmd: 1 << 20,
+    command: 1 << 20,
+}
+
+const NAMED_KEYS: Record<string, string> = {
+    enter: '\r',
+    return: '\r',
+    tab: '\t',
+    escape: '\x1b',
+    esc: '\x1b',
+    backspace: '\b',
+    delete: '\x7f',
+    space: ' ',
+    up: '',
+    down: '',
+    left: '',
+    right: '',
+}
+
+/**
+ * The menu bar the window shows: the application, File, Edit, View and Window menus, and `added`.
+ *
+ * 38.89 — AN ADDED MENU NAMED AS A DEFAULT ONE GROWS IT, and any other stands before Window, where
+ * the platform puts an app's own. 38.84 — no Connect… where `launcher.json` turns connecting off.
+ */
+export function menuBar(
+    appName: string,
+    connect: boolean,
+    added: NativeItem[],
+): NativeItem[] {
+    const bar = defaultMenu(appName, connect)
+    const window = bar.pop() as NativeItem
+    for (const menu of added) {
+        const named =
+            menu === 'separator'
+                ? undefined
+                : bar.find(
+                      (standing) =>
+                          standing !== 'separator' &&
+                          standing.label === menu.label,
+                  )
+        if (
+            named === undefined ||
+            named === 'separator' ||
+            menu === 'separator'
+        )
+            bar.push(menu)
+        else named.items = [...(named.items ?? []), ...(menu.items ?? [])]
+    }
+    bar.push(window)
+    return bar
+}
+
+function defaultMenu(appName: string, connect: boolean): NativeItem[] {
+    return [
+        {
+            label: appName,
+            items: [
+                { label: `About ${appName}`, role: 'about' },
+                'separator',
+                { label: `Hide ${appName}`, role: 'hide', key: 'cmd+h' },
+                { label: 'Hide Others', role: 'hideOthers', key: 'cmd+alt+h' },
+                { label: 'Show All', role: 'showAll' },
+                'separator',
+                { label: `Quit ${appName}`, role: 'quit', key: 'cmd+q' },
+            ],
+        },
+        {
+            label: 'File',
+            items: [
+                ...(connect
+                    ? ([
+                          { label: 'Connect…', role: 'connect', key: 'cmd+k' },
+                      ] as NativeItem[])
+                    : []),
+                { label: 'Disconnect', role: 'disconnect', key: 'cmd+shift+k' },
+                'separator',
+                { label: 'Close Window', role: 'close', key: 'cmd+w' },
+            ],
+        },
+        {
+            label: 'Edit',
+            items: [
+                { label: 'Undo', role: 'undo', key: 'cmd+z' },
+                { label: 'Redo', role: 'redo', key: 'cmd+shift+z' },
+                'separator',
+                { label: 'Cut', role: 'cut', key: 'cmd+x' },
+                { label: 'Copy', role: 'copy', key: 'cmd+c' },
+                { label: 'Paste', role: 'paste', key: 'cmd+v' },
+                { label: 'Select All', role: 'selectAll', key: 'cmd+a' },
+            ],
+        },
+        {
+            label: 'View',
+            items: [
+                { label: 'Reload', role: 'reload', key: 'cmd+r' },
+                'separator',
+                {
+                    label: 'Enter Full Screen',
+                    role: 'fullscreen',
+                    key: 'ctrl+cmd+f',
+                },
+            ],
+        },
+        {
+            label: 'Window',
+            items: [
+                { label: 'Minimize', role: 'minimize', key: 'cmd+m' },
+                { label: 'Zoom', role: 'zoom' },
+                'separator',
+                { label: 'Bring All to Front', role: 'front' },
+            ],
+        },
+    ]
+}
+
+type Choice = Exclude<NativeItem, 'separator'>
+
+// What each launcher-handled item fires, by the tag its `NSMenuItem` carries.
+let chosen: Choice[] = []
+let onChoice: (item: Choice) => void = () => {}
+let target: Id = null
+
+/**
+ * Builds `menu` as the application's menu bar; `choose` is handed each item AppKit does not answer
+ * itself when it is picked.
+ */
+export function installMenu(
+    menu: NativeItem[],
+    choose: (item: Choice) => void,
+): void {
+    target ??= send(
+        definedClass('AbideMenuTarget', {
+            'choose:': {
+                types: 'v@:@',
+                args: [FFIType.ptr],
+                returns: FFIType.void,
+                run: (item: Id) => {
+                    const picked =
+                        chosen[
+                            Number(
+                                sendTyped(
+                                    item,
+                                    'tag',
+                                    [],
+                                    FFIType.i64,
+                                ) as bigint,
+                            )
+                        ]
+                    if (picked !== undefined) onChoice(picked)
+                },
+            },
+        }),
+        'new',
+    )
+    chosen = []
+    onChoice = choose
+    const bar = send(objcClass('NSMenu'), 'new')
+    for (const item of menu) send(bar, 'addItem:', menuItem(item))
+    send(
+        send(objcClass('NSApplication'), 'sharedApplication'),
+        'setMainMenu:',
+        bar,
+    )
+}
+
+function menuItem(item: NativeItem): Id {
+    if (item === 'separator')
+        return send(objcClass('NSMenuItem'), 'separatorItem')
+    const { keyEquivalent, modifiers } = shortcut(item.key)
+    const responder =
+        item.role === undefined ? undefined : RESPONDER_ROLES[item.role]
+    const built = send(
+        send(objcClass('NSMenuItem'), 'alloc'),
+        'initWithTitle:action:keyEquivalent:',
+        nsString(item.label),
+        null,
+        nsString(keyEquivalent),
+    )
+    sendTyped(
+        built,
+        'setKeyEquivalentModifierMask:',
+        [FFIType.u64],
+        FFIType.void,
+        modifiers,
+    )
+    if (item.items !== undefined) {
+        const submenu = send(
+            send(objcClass('NSMenu'), 'alloc'),
+            'initWithTitle:',
+            nsString(item.label),
+        )
+        for (const child of item.items)
+            send(submenu, 'addItem:', menuItem(child))
+        send(built, 'setSubmenu:', submenu)
+        return built
+    }
+    if (responder !== undefined) {
+        sendTyped(
+            built,
+            'setAction:',
+            [FFIType.ptr],
+            FFIType.void,
+            selector(responder),
+        )
+        return built
+    }
+    sendTyped(
+        built,
+        'setAction:',
+        [FFIType.ptr],
+        FFIType.void,
+        selector('choose:'),
+    )
+    send(built, 'setTarget:', target)
+    sendTyped(built, 'setTag:', [FFIType.i64], FFIType.void, chosen.length)
+    chosen.push(item)
+    return built
+}
+
+/** A shortcut as AppKit spells it: the key, and the mask of the modifiers written before it. */
+function shortcut(key: string | undefined): {
+    keyEquivalent: string
+    modifiers: number
+} {
+    if (key === undefined || key === '')
+        return { keyEquivalent: '', modifiers: 0 }
+    const parts = key.toLowerCase().split('+')
+    const last = parts.pop() as string
+    let modifiers = 0
+    for (const part of parts) modifiers |= MODIFIERS[part] ?? 0
+    const named = NAMED_KEYS[last]
+    const function_ = /^f([1-9]|1[0-2])$/.exec(last)
+    const keyEquivalent =
+        named ??
+        (function_ === null
+            ? last
+            : String.fromCharCode(0xf704 + Number(function_[1]) - 1))
+    return { keyEquivalent, modifiers }
+}

package/src/server/negotiateEncoding.ts

@@ -0,0 +1,39 @@
+// 38.30 — WHICH OF THE ENCODINGS ON OFFER A REQUEST TAKES, or `undefined` for the bytes as they
+// are. What is on offer is asked rather than assumed: a request preferring brotli for a file with
+// only a gzip copy takes the gzip, where picking first and checking after would send it neither.
+//
+// The highest quality the request gives an encoding wins, a tie goes to the one offered first,
+// and `q=0` is a refusal rather than a low preference — so `br;q=0, *` is gzip and `*;q=0` is
+// nothing, which a parse that only looked for the token would get wrong both ways.
+
+import { ENCODING_SUFFIX } from './CLIENT_BUILD.ts'
+import { qualitiesOf } from './qualitiesOf.ts'
+
+export type Encoding = keyof typeof ENCODING_SUFFIX
+
+/**
+ * Every encoding, in `ENCODING_SUFFIX`'s order.
+ *
+ * What a document rendered per request can offer.
+ */
+export const ENCODINGS = Object.keys(ENCODING_SUFFIX) as Encoding[]
+
+/** The encoding on offer the request takes, or `undefined` for the bytes as they are. */
+export function negotiateEncoding(
+    accepted: string | null,
+    offered: readonly Encoding[],
+): Encoding | undefined {
+    if (accepted === null) return undefined
+    const qualities = qualitiesOf(accepted)
+    const wildcard = qualities.get('*') ?? 0
+    let chosen: Encoding | undefined
+    let best = 0
+    for (const encoding of offered) {
+        const quality = qualities.get(encoding) ?? wildcard
+        if (quality > best) {
+            best = quality
+            chosen = encoding
+        }
+    }
+    return chosen
+}

package/src/server/plainAnswer.ts

@@ -0,0 +1,19 @@
+/**
+ * A plain-text answer at `status`, never stored.
+ *
+ * 21.3 — A REFUSAL ABIDE ANSWERS AS TEXT, typed. `stamp` rebuilds an answer to give it a reason
+ * phrase (17.8), and a string body rebuilt goes out as `application/octet-stream`.
+ *
+ * 21.1 — `nosniff` HERE TOO, though `stamp` sets it on whatever an app answers: `abide dev`'s
+ * listener answers with this where no app stands behind it, and nothing stamps those.
+ */
+export function plainAnswer(message: string, status: number): Response {
+    return new Response(message, {
+        status,
+        headers: {
+            'content-type': 'text/plain; charset=utf-8',
+            'cache-control': 'private, no-store',
+            'x-content-type-options': 'nosniff',
+        },
+    })
+}

package/src/server/prefers.ts

@@ -0,0 +1,25 @@
+import { qualitiesOf } from './qualitiesOf.ts'
+
+/**
+ * Whether the request's `accept` header takes `wanted` over `over`.
+ *
+ * Listed at a higher quality, or at the same one and ahead of it. `wanted` has to be NAMED — a
+ * wildcard says nothing about which the reader prefers — and `wanted;q=0` is a refusal of it, not
+ * a low preference.
+ */
+export function prefers(
+    request: Request,
+    wanted: string,
+    over: string,
+): boolean {
+    const qualities = qualitiesOf(request.headers.get('accept') ?? '')
+    const wantedQuality = qualities.get(wanted) ?? 0
+    if (wantedQuality <= 0) return false
+    const overQuality = qualities.get(over) ?? 0
+    if (wantedQuality !== overQuality) return wantedQuality > overQuality
+    for (const token of qualities.keys()) {
+        if (token === wanted) return true
+        if (token === over) return false
+    }
+    return false
+}

package/src/server/principal.ts

@@ -0,0 +1,261 @@
+// SECTION 26 — THE PRINCIPAL, RESOLVED ON A SERVER. The claims ride in a cookie the server sealed —
+// a JWT signed HS256, the claims its payload beside `exp` and `iat`, signed rather than encrypted
+// (26.11), so any service holding the secret can verify it — and so there is no
+// store to look them up in and nothing to revoke (26.16). Resolved at most once per request (26.14),
+// by `onPrincipal` where the app registered one, and the baseline is laid over what it answered (26.4).
+
+import { PRINCIPAL_ADDRESS } from '#shared/ADDRESSES.ts'
+import { cookies } from '#shared/cookies.ts'
+import { isFailed } from '#shared/Failed.ts'
+import { isRecord } from '#shared/isRecord.ts'
+import { namedLogger } from '#shared/log.ts'
+import { PRINCIPAL_HEADER } from '#shared/PRINCIPAL_HEADER.ts'
+import {
+    type PRINCIPAL,
+    type Principal,
+    principalMembers,
+} from '#shared/principal.ts'
+import { refuse } from '#shared/refuse.ts'
+import { declare } from '#shared/rpc.ts'
+import { mountedOwn } from './answerRpc.ts'
+import { callerOrMint, mintCaller } from './callerOf.ts'
+import { config, positiveSetting } from './config.ts'
+import { HOOKS } from './hooks.ts'
+import { within } from './requestScope.ts'
+
+// 26.18.
+const PRINCIPAL_COOKIE = 'abide-principal'
+// 26.20 — the ceiling a browser keeps one cookie under, name and attributes included.
+const COOKIE_CEILING = 4096
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+const PRINCIPAL_LOG = namedLogger('abide:principal')
+
+const ANONYMOUS: Principal = { authenticated: false }
+
+function ttl(): number {
+    return positiveSetting('ABIDE_PRINCIPAL_TTL', DEFAULT_TTL_MS)
+}
+
+/**
+ * The secrets in `ABIDE_PRINCIPAL_SECRET`, signing one first.
+ *
+ * 36.5 — A LIST: the first secret signs, and every one verifies, so a secret can be rotated in.
+ */
+function secrets(): string[] {
+    const declared = config.peek()?.ABIDE_PRINCIPAL_SECRET
+    if (typeof declared !== 'string') return []
+    const listed: string[] = []
+    for (const part of declared.split(','))
+        if (part.trim() !== '') listed.push(part.trim())
+    return listed
+}
+
+function signature(secret: string, payload: string): string {
+    return new Bun.CryptoHasher('sha256', secret)
+        .update(payload)
+        .digest('base64url')
+}
+
+/** The JWT header every seal carries, and the only one a seal is read under: HS256, never `none`. */
+const JWT_HEADER = Buffer.from(
+    JSON.stringify({ alg: 'HS256', typ: 'JWT' }),
+).toString('base64url')
+
+/** The claims as a JWT (RFC 7519): their own members, with `exp` and `iat` in seconds. */
+function seal(
+    claims: Record<string, unknown>,
+    expires: number,
+    secret: string,
+): string {
+    const payload = Buffer.from(
+        JSON.stringify({
+            ...claims,
+            iat: Math.floor(Date.now() / 1000),
+            exp: Math.floor(expires / 1000),
+        }),
+    ).toString('base64url')
+    const signed = `${JWT_HEADER}.${payload}`
+    return `${signed}.${signature(secret, signed)}`
+}
+
+/**
+ * The claims and expiry a sealed cookie holds, or `undefined`.
+ *
+ * 26.13 — A BAD SIGNATURE, A LAPSED SEAL AND A MALFORMED COOKIE ARE ONE ANSWER: nothing.
+ */
+function unseal(
+    sealed: string | null,
+): { claims: Record<string, unknown>; expires: number } | undefined {
+    if (sealed === null) return undefined
+    const [header, payload, signed, ...rest] = sealed.split('.')
+    // ONE HEADER IS READ, abide's own: a token naming another `alg` — `none` above all — is no seal.
+    if (header !== JWT_HEADER || payload === undefined || rest.length > 0)
+        return undefined
+    const given = Buffer.from(signed ?? '', 'base64url')
+    let verified = false
+    for (const secret of secrets()) {
+        const expected = Buffer.from(
+            signature(secret, `${header}.${payload}`),
+            'base64url',
+        )
+        if (
+            expected.length === given.length &&
+            crypto.timingSafeEqual(expected, given)
+        )
+            verified = true
+    }
+    if (!verified) return undefined
+    try {
+        const opened: unknown = JSON.parse(
+            Buffer.from(payload, 'base64url').toString(),
+        )
+        if (!isRecord(opened)) return undefined
+        const { exp, iat: _, ...claims } = opened
+        if (typeof exp !== 'number' || exp * 1000 <= Date.now())
+            return undefined
+        return { claims, expires: exp * 1000 }
+    } catch {
+        return undefined
+    }
+}
+
+function writeSeal(claims: Record<string, unknown>, expires: number): void {
+    const [secret] = secrets()
+    if (secret === undefined)
+        throw new Error(
+            'abide: principal.set needs ABIDE_PRINCIPAL_SECRET to seal the cookie with.',
+        )
+    const sealed = seal(claims, expires, secret)
+    // 26.20.
+    const bytes = PRINCIPAL_COOKIE.length + 1 + sealed.length
+    if (bytes > COOKIE_CEILING)
+        throw new Error(
+            `abide: principal.set would write a ${bytes}-byte cookie, over the ${COOKIE_CEILING} bytes a browser keeps. Seal less in the claims.`,
+        )
+    // 26.12.
+    cookies().set(PRINCIPAL_COOKIE, sealed, {
+        httpOnly: true,
+        sameSite: 'lax',
+        maxAge: Math.floor((expires - Date.now()) / 1000),
+    })
+}
+
+async function documentOf(
+    claims: unknown,
+    expires: number,
+): Promise<Principal> {
+    const baseline = {
+        authenticated: true,
+        expiresAt: new Date(expires).toISOString(),
+        error: undefined,
+    }
+    const resolve = HOOKS.principal
+    if (resolve === undefined)
+        return { ...(isRecord(claims) ? claims : {}), ...baseline }
+    try {
+        const resolved = await resolve(claims)
+        return { ...(isRecord(resolved) ? resolved : {}), ...baseline }
+    } catch (thrown) {
+        // 26.3 — a resolver that failed leaves the caller unauthenticated, and says why.
+        PRINCIPAL_LOG.warning('onPrincipal threw', thrown)
+        return {
+            authenticated: false,
+            expiresAt: undefined,
+            error: isFailed(thrown)
+                ? thrown
+                : refuse(500, 'onPrincipal failed'),
+        }
+    }
+}
+
+/**
+ * This request's principal, resolved from its cookie at most once.
+ *
+ * 26.14 — ONCE PER REQUEST, and 26.15 — a seal half spent is sealed again for another full life.
+ */
+function resolvePrincipal(): Promise<Principal> {
+    const scope = within('principal')
+    scope.principal ??= (async () => {
+        const opened = unseal(cookies().get(PRINCIPAL_COOKIE))
+        if (opened === undefined) return ANONYMOUS
+        let expires = opened.expires
+        const life = ttl()
+        if (expires - Date.now() < life / 2 && scope.applied === false) {
+            expires = Date.now() + life
+            writeSeal(opened.claims, expires)
+        }
+        return documentOf(opened.claims, expires)
+    })()
+    return scope.principal
+}
+
+/**
+ * Signs this caller in with `claims`, sealing them into the cookie.
+ *
+ * 26.8, 26.21 — AUTHENTICATES THIS CALLER, before the headers are out, leaving `caller` where it
+ * was. The answer says so in `PRINCIPAL_HEADER`, which is what has the browser's `principal` load
+ * the document again: the cookie it rides in is `HttpOnly`, and a `set-cookie` is a header no
+ * `fetch` may read.
+ */
+async function set(claims: Record<string, unknown>): Promise<void> {
+    const scope = within('principal.set')
+    // 26.11 — THE CLAIMS ARE A JWT's PAYLOAD, so they are its members: an object, and nothing else.
+    if (!isRecord(claims))
+        throw new Error(
+            'abide: principal.set takes an object of claims, which become the JWT payload. RULEBOOK 26.11.',
+        )
+    if (scope.applied)
+        throw new Error(
+            'abide: principal.set was called after the response headers went out, so the cookie cannot be written. RULEBOOK 26.21.',
+        )
+    const expires = Date.now() + ttl()
+    writeSeal(claims, expires)
+    scope.response.headers.set(PRINCIPAL_HEADER, 'set')
+    const resolved = documentOf(claims, expires)
+    scope.principal = resolved
+    principalMembers().document.set(await resolved)
+    PRINCIPAL_LOG.debug('set')
+}
+
+/**
+ * Signs this caller out and rotates `caller`.
+ *
+ * 26.7, 26.9 — SIGNS OUT NOW AND NEXT TIME, and rotates `caller` so the next visitor at this
+ * browser is not the last one.
+ */
+function clear(): void {
+    const scope = within('principal.clear')
+    cookies().delete(PRINCIPAL_COOKIE)
+    scope.response.headers.set(PRINCIPAL_HEADER, 'clear')
+    const minted = mintCaller(scope)
+    scope.principal = Promise.resolve(ANONYMOUS)
+    principalMembers().document.set(ANONYMOUS)
+    principalMembers().caller.set(minted)
+    PRINCIPAL_LOG.debug('clear')
+}
+
+// 26.17 — THE DOCUMENT IS A `GET` LIKE ANY OTHER, so it reaches a browser as any handler's value does
+// (41.5): a render's read of it is reported as the call it is, left in the seed buffer (41.13) and
+// started from the head (41.20), and the browser's own read takes that answer rather than asking
+// again. Built on the core's `declare` with no generated surface (20.1) — abide mounts it, not the
+// app's tree.
+const principalDocument = declare('GET')(resolvePrincipal, {
+    clients: { ui: false, mcp: false, cli: false, openapi: false },
+})
+
+/** The handler `/__abide/principal` is answered by. */
+export const PRINCIPAL_MOUNT = mountedOwn(
+    PRINCIPAL_ADDRESS,
+    'principal',
+    principalDocument,
+)
+
+// 21.3 — the answer is about this caller alone, and is never cached. 1.4 — the call's `Reactive` is
+// thenable, and a promise of it is the document.
+export const SERVER_PRINCIPAL: typeof PRINCIPAL = {
+    document: () => Promise.resolve(principalDocument()),
+    caller: callerOrMint,
+    set,
+    clear,
+}

package/src/server/qualitiesOf.ts

@@ -0,0 +1,22 @@
+/**
+ * Each token of a `;q=`-weighted list header, to its quality, in the order the header lists them.
+ *
+ * For `accept` and `accept-encoding`. A QUALITY THAT DOES NOT PARSE REFUSES, rather than reading as
+ * the default of 1, and `q=0` is a refusal rather than a low preference.
+ */
+export function qualitiesOf(header: string): Map<string, number> {
+    const qualities = new Map<string, number>()
+    for (const part of header.split(',')) {
+        const [token, ...parameters] = part.split(';')
+        let quality = 1
+        for (const parameter of parameters) {
+            const [key, value] = parameter.split('=')
+            if (key?.trim() === 'q') quality = Number(value)
+        }
+        qualities.set(
+            (token as string).trim().toLowerCase(),
+            Number.isNaN(quality) ? 0 : quality,
+        )
+    }
+    return qualities
+}

package/src/server/randomToken.ts

@@ -0,0 +1,9 @@
+/** `bytes` random bytes, encoded as `encoding`. */
+export function randomToken(
+    bytes: number,
+    encoding: 'base64' | 'base64url' | 'hex',
+): string {
+    return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString(
+        encoding,
+    )
+}