@abide/abide 0.58.0 → 0.101.0

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,
+    )
+}

package/src/server/reachable.ts

@@ -0,0 +1,31 @@
+// 23.10-23.13 — WHETHER A HOST ANSWERS AT ALL, asked before a call to it. A warm answer turns every
+// call queued behind a host that is down into an instant refusal, where each would otherwise burn a
+// network timeout of its own.
+//
+// ANY ANSWER IS REACHABLE: a 404 or a 500 came from the host, so only a request that never got one
+// — refused, unresolved, timed out — is `false`. `HEAD`, so the answer carries no body to read.
+
+import { reactive } from '#shared/reactive/index.ts'
+
+const PROBE_TIMEOUT_MILLISECONDS = 5_000
+const ANSWER_HELD_MILLISECONDS = 60_000
+
+const answering = reactive(
+    async ({ host }: { host: string }) => {
+        try {
+            await fetch(host.includes('://') ? host : `https://${host}/`, {
+                method: 'HEAD',
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MILLISECONDS),
+            })
+            return true
+        } catch {
+            return false
+        }
+    },
+    { global: true, ttl: ANSWER_HELD_MILLISECONDS },
+)
+
+/** Whether `host` answers at all: a bare host over https, or an origin as written. */
+export function reachable(host: string): Promise<boolean> {
+    return Promise.resolve(answering({ host }))
+}

package/src/server/refuseAddressCollision.ts

@@ -0,0 +1,30 @@
+import { PUBLIC_DIRECTORY } from './CLIENT_BUILD.ts'
+
+/**
+ * Throws, naming both, when a public file and a page claim the same address.
+ *
+ * 36.13 — A PUBLIC FILE AND A PAGE MAY NOT CLAIM ONE ADDRESS. The two are separate walks of two
+ * separate trees, so from inside either one the collision is invisible; this is the one place
+ * they meet, and naming BOTH is the clause — naming one leaves the reader to find the other.
+ *
+ * THE BUILD AND DEV, and `abide start` trusts the build: `answerRequest` answers a public file
+ * AHEAD of any route on the ground that 36.13 makes a collision impossible at run time, and 30.8
+ * says dev must resolve an address the way the built app does.
+ *
+ * PUBLIC ADDRESSES IN, so a caller hands whichever it already holds: the build derives one per
+ * globbed name (36.11 — the path below the directory IS the address) and the dev worker's
+ * `published` map is keyed by them already.
+ */
+export function refuseAddressCollision(
+    routes: readonly { pattern: string }[],
+    publicAddresses: Iterable<string>,
+    command: string,
+): void {
+    const patterns = new Set<string>()
+    for (const route of routes) patterns.add(route.pattern)
+    for (const address of publicAddresses)
+        if (patterns.has(address))
+            throw new Error(
+                `${command}: ui/${PUBLIC_DIRECTORY}${address} and the page at ${address} claim the same address. RULEBOOK 36.13.`,
+            )
+}

package/src/server/remote.ts

@@ -0,0 +1,242 @@
+// THE CLIENT FOR A RUNNING APP — what the shell (`shell.ts`), `call`, `logs`, `openapi` and `mcp` talk to
+// it with, the shell on the app served here included.
+// Which app is `--url`, then `ABIDE_APP_URL`, then the local one; `ABIDE_APP_TOKEN` is the bearer
+// sent (36.6), and neither variable is read anywhere else.
+
+import { LOGS_ADDRESS, RPC_ADDRESS } from '#shared/ADDRESSES.ts'
+import { applyPatch } from '#shared/applyPatch.ts'
+import type { LogRecord } from '#shared/log.ts'
+import type { PatchOp } from '#shared/reactive/PATCH_SINKS.ts'
+import type { Method } from '#shared/rpc.ts'
+import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
+import type { Mount } from './answerRpc.ts'
+import { DEFAULT_PORT } from './DEFAULT_PORT.ts'
+import { withoutTrailingSlash } from './withoutTrailingSlash.ts'
+
+/**
+ * The running app asked for, or `undefined` where none is.
+ *
+ * `undefined` is where `openapi` and `mcp` boot the local one instead.
+ */
+export function remoteUrl(given: string | undefined): string | undefined {
+    return given ?? process.env.ABIDE_APP_URL
+}
+
+/** The URL of the running app asked for, or the local one, with no trailing slash. */
+export function appUrl(given: string | undefined): string {
+    return withoutTrailingSlash(
+        remoteUrl(given) ??
+            `http://localhost:${process.env.PORT ?? DEFAULT_PORT}`,
+    )
+}
+
+/** The headers a call to a running app carries: `ABIDE_APP_TOKEN` as the bearer, where set. */
+export function remoteHeaders(): Record<string, string> {
+    const token = process.env.ABIDE_APP_TOKEN
+    return token === undefined ? {} : { authorization: `Bearer ${token}` }
+}
+
+// The exit codes the CLI answers a call with: 0 answered, 7 refused, 8 faulted.
+const REFUSED = 7
+const FAULTED = 8
+
+/**
+ * Calls one handler on a running app; returns the CLI's exit code and the answer's text.
+ *
+ * 38.8 — ONE CALL TO ONE HANDLER, spelled `invoices/getInvoice id=4310` in argv and in the shell
+ * alike, and 38.62's args.
+ */
+export async function callHandler(
+    url: string,
+    path: string,
+    given: string[],
+    method: string | undefined,
+    handlers: Mount[],
+    signal?: AbortSignal,
+): Promise<{ code: number; text: string }> {
+    const address = `${RPC_ADDRESS}/${path.replace(/^\//, '')}`
+    const handler = handlers.find((mount) => mount.address === address)
+    const args = callArgs(given)
+    const chosen = (method?.toUpperCase() ??
+        (handler?.method as Method | undefined) ??
+        (args === undefined ? 'GET' : 'POST')) as Method
+    const request =
+        args instanceof URLSearchParams
+            ? textRequest(chosen, address, args)
+            : rpcRequest(chosen, address, args)
+    const answer = await fetch(`${url}${request.url}`, {
+        ...request.init,
+        headers: { ...remoteHeaders(), ...request.init.headers },
+        signal: signal ?? null,
+    })
+    const text = await answer.text()
+    const code =
+        answer.status >= 500 ? FAULTED : answer.status >= 400 ? REFUSED : 0
+    return { code, text }
+}
+
+/**
+ * A call's args out of the words after its address, or `undefined` where there are none.
+ *
+ * 38.62 — `name=value` words, kept as the text they are for the app to coerce as it coerces a query's
+ * (19.7), against the schema it holds the call to; or, where the first word opens one, a JSON object.
+ */
+function callArgs(
+    given: string[],
+): Record<string, unknown> | URLSearchParams | undefined {
+    // An empty word is no arg, as `call x ''` from a script means none.
+    const words: string[] = []
+    for (const word of given) if (word.trim() !== '') words.push(word)
+    if (words.length === 0) return undefined
+    if ((words[0] as string).trimStart().startsWith('{'))
+        return JSON.parse(words.join(' ')) as Record<string, unknown>
+    const pairs = new URLSearchParams()
+    for (const word of words) {
+        const at = word.indexOf('=')
+        if (at < 1)
+            throw new Error(
+                `call: args are name=value, or one JSON object — not '${word}'`,
+            )
+        pairs.append(word.slice(0, at), word.slice(at + 1))
+    }
+    return pairs
+}
+
+/** The request a call with text args is: in the URL where its method carries them, a form where not. */
+function textRequest(
+    method: Method,
+    address: string,
+    pairs: URLSearchParams,
+): { url: string; init: RequestInit } {
+    if (argsInURL(method))
+        return { url: `${address}?${pairs}`, init: { method } }
+    return {
+        url: address,
+        init: {
+            method,
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: pairs.toString(),
+        },
+    }
+}
+
+/**
+ * Prints every line `log.records` publishes, as it is written; returns the exit code.
+ *
+ * 38.10.
+ */
+export async function followLogs(url: string): Promise<number> {
+    const answer = await fetch(`${url}${LOGS_ADDRESS}`, {
+        headers: { ...remoteHeaders(), accept: 'text/event-stream' },
+    })
+    if (!answer.ok || answer.body === null) {
+        console.error(
+            `logs: the app answered ${answer.status}. ABIDE_LOGS opens the subscription.`,
+        )
+        return 1
+    }
+    // 18.20 — the lines held arrive as the value, and each line after as an `add` at `/-`; a trim's
+    // `remove`s are the buffer letting old lines go, which a tail has already printed.
+    for await (const event of eventsOf(answer.body)) {
+        if (event.name === 'error') console.error(`logs: ${event.data}`)
+        const lines =
+            event.name === 'value'
+                ? ((JSON.parse(event.data) as LogRecord[] | null) ?? [])
+                : event.name === 'patch'
+                  ? addedBy(JSON.parse(event.data) as PatchOp[])
+                  : []
+        for (const { time, level, namespace, message } of lines)
+            console.log(`${time} ${level} ${namespace} ${message}`)
+    }
+    return 0
+}
+
+/** The records a patch appended: the value of each `add`. */
+function addedBy(ops: PatchOp[]): LogRecord[] {
+    const added: LogRecord[] = []
+    for (const op of ops) if (op.op === 'add') added.push(op.value as LogRecord)
+    return added
+}
+
+/**
+ * Follows a `GET` of the app at `url` as an event stream, printing its value and its value after each
+ * patch; returns the exit code.
+ *
+ * 38.70, 18.20 — THE EVENT STREAM ANY CLIENT MAY ASK A FOLLOWED `GET` FOR, read by one: `event: value`
+ * replaces what is held and `event: patch` is JSON Patch applied over it. A handler the server does
+ * not follow — one built per request — answers once, and is printed once.
+ */
+export async function watch(
+    url: string,
+    address: string,
+    given: string[],
+    signal?: AbortSignal,
+): Promise<number> {
+    const path = `${RPC_ADDRESS}/${address.replace(/^\//, '')}`
+    const args = callArgs(given)
+    const request =
+        args instanceof URLSearchParams
+            ? textRequest('GET', path, args)
+            : rpcRequest('GET', path, args)
+    const answer = await fetch(`${url}${request.url}`, {
+        ...request.init,
+        headers: {
+            ...remoteHeaders(),
+            ...(request.init.headers as Record<string, string> | undefined),
+            accept: 'text/event-stream',
+        },
+        signal: signal ?? null,
+    })
+    if (!answer.ok) {
+        console.error(`watch: ${await answer.text()}`)
+        return 1
+    }
+    const type = answer.headers.get('content-type') ?? ''
+    if (!type.startsWith('text/event-stream') || answer.body === null) {
+        console.log(await answer.text())
+        return 0
+    }
+    let held: unknown
+    for await (const event of eventsOf(answer.body)) {
+        if (event.name === 'value') held = JSON.parse(event.data)
+        else if (event.name === 'patch')
+            applyPatch(held, JSON.parse(event.data) as PatchOp[])
+        else {
+            // A refresh the handler refused: what is held stays, and the refusal is said.
+            if (event.name === 'error') console.error(`watch: ${event.data}`)
+            continue
+        }
+        console.log(JSON.stringify(held))
+    }
+    return 0
+}
+
+/** Each event of an event stream: its `event` name, `message` where it named none, and its `data`. */
+async function* eventsOf(
+    body: ReadableStream<Uint8Array>,
+): AsyncIterable<{ name: string; data: string }> {
+    const decoder = new TextDecoder()
+    let buffered = ''
+    for await (const chunk of body) {
+        buffered += decoder.decode(chunk, { stream: true })
+        for (
+            let end = buffered.indexOf('\n\n');
+            end !== -1;
+            end = buffered.indexOf('\n\n')
+        ) {
+            const block = buffered.slice(0, end)
+            buffered = buffered.slice(end + 2)
+            let name = 'message'
+            let data: string | undefined
+            for (const line of block.split('\n')) {
+                if (line.startsWith('event:')) name = line.slice(6).trim()
+                else if (line.startsWith('data:')) {
+                    const field = line.slice(5).replace(/^ /, '')
+                    data = data === undefined ? field : `${data}\n${field}`
+                }
+            }
+            // A comment alone — the stream's opener — is no event.
+            if (data !== undefined) yield { name, data }
+        }
+    }
+}