@fabrika/app 0.3.3 → 0.4.1

package/src/service/define.ts

@@ -0,0 +1,121 @@
+// A service contract: the endpoint table of one of the installation's own services (ADR-0012, ADR-0022 "Installation
+// entries"). Plain data over `@fabrika/auth-core` only, so a table module stays dependency-light.
+
+import {
+	APP_ENVIRONMENT_SEPARATOR,
+	type BodyAdmission,
+	compileEndpointTable,
+	EndpointTableError,
+	type InstallationCaller,
+	type InstallationEndpointMethod,
+	type InstallationEndpointRow,
+	type InstallationEndpointTable,
+	OAUTH_CALLER,
+} from '@fabrika/auth-core'
+
+/** A row as the builder writes it; the record key of `endpoints` becomes its id. */
+export type ServiceEndpointSpec = InstallationEndpointRow extends infer Row ? Row extends InstallationEndpointRow ? Omit<Row, 'id'> : never : never
+
+/** One installation service's table, with the row ids as a type so its handlers can be checked against them. */
+export interface ServiceArtifact<Id extends string = string> extends InstallationEndpointTable {
+	/** The service's IAM app id; never `<app>@<env>`. */
+	readonly id: string
+	readonly endpoints: readonly (InstallationEndpointRow & { readonly id: Id })[]
+}
+
+export interface ServiceEndpointOptions {
+	readonly callers: readonly [InstallationCaller, ...InstallationCaller[]]
+	/** The request body the row admits; omitted admits none. */
+	readonly admission?: BodyAdmission
+	/** The scopes an OAuth resource token must carry; required exactly when `callers` holds `oauth`. */
+	readonly scopes?: readonly string[]
+}
+
+export interface ServiceContractBuilder {
+	/** A liveness endpoint: anonymous, and served without `X-Fabrika-Endpoint`. */
+	health(method: InstallationEndpointMethod, path: string): ServiceEndpointSpec
+	/** An endpoint the service authenticates itself; the proxy reads no credential and keeps `Authorization`. */
+	protocol(method: InstallationEndpointMethod, path: string): ServiceEndpointSpec
+	/** A credentialed endpoint: a listed caller kind, and no permission (`authenticated`). */
+	service(method: InstallationEndpointMethod, path: string, options: ServiceEndpointOptions): ServiceEndpointSpec
+}
+
+export interface ServiceContractDeclaration<Id extends string> {
+	/** `null` is a row this composition does not serve: the table has no row there, and its handler is never called. */
+	readonly endpoints: Readonly<Record<Id, ServiceEndpointSpec | null>>
+	/** Literal prefixes a path under which reaches only a row declared under it. */
+	readonly reservedPrefixes: readonly string[]
+}
+
+export class ServiceContractError extends Error {
+	override readonly name = 'ServiceContractError'
+	readonly problems: readonly string[]
+
+	constructor(problems: readonly string[]) {
+		super(`the service contract is invalid:\n- ${problems.join('\n- ')}`)
+		this.problems = problems
+	}
+}
+
+const builder: ServiceContractBuilder = {
+	health: (method, path) => anonymous('health', method, path),
+	protocol: (method, path) => anonymous('protocol', method, path),
+	service: (method, path, options) => ({
+		kind: 'service',
+		method,
+		path,
+		callers: options.callers,
+		requirement: { kind: 'authenticated' },
+		admission: options.admission ?? null,
+		oauth: options.scopes === undefined ? null : { scopes: options.scopes },
+	}),
+}
+
+function anonymous(kind: 'health' | 'protocol', method: InstallationEndpointMethod, path: string): ServiceEndpointSpec {
+	return { kind, method, path, callers: [], requirement: null, admission: null, oauth: null }
+}
+
+/**
+ * Declare one installation service's endpoint table. Validated here, once: an id that is an application environment,
+ * an `oauth` caller without its scopes (or scopes without it), and every table the matcher would refuse.
+ */
+export function defineServiceContract<const Id extends string>(
+	id: string,
+	declare: (s: ServiceContractBuilder) => ServiceContractDeclaration<Id>,
+): ServiceArtifact<Id> {
+	const declaration = declare(builder)
+	const endpoints = servedEntries(declaration.endpoints).map(([rowId, spec]) => ({ ...spec, id: rowId }))
+	const problems: string[] = []
+	if (id === '' || id.includes(APP_ENVIRONMENT_SEPARATOR)) {
+		problems.push(`'${id}' is no installation service id: it must be non-empty and hold no '${APP_ENVIRONMENT_SEPARATOR}'`)
+	}
+	for (const row of endpoints) {
+		const admitsOAuth = row.callers.some((caller) => caller === OAUTH_CALLER)
+		if (admitsOAuth !== (row.oauth !== null)) {
+			problems.push(`'${row.id}' must declare scopes exactly when it admits the caller '${OAUTH_CALLER}'`)
+		}
+		if (row.oauth !== null && row.oauth.scopes.length === 0) {
+			problems.push(`'${row.id}' admits '${OAUTH_CALLER}' with no scope`)
+		}
+	}
+	const table = { endpoints, reservedPrefixes: [...declaration.reservedPrefixes] }
+	try {
+		compileEndpointTable(table)
+	} catch (error) {
+		if (!(error instanceof EndpointTableError)) throw error
+		problems.push(...error.problems)
+	}
+	if (problems.length > 0) {
+		throw new ServiceContractError(problems)
+	}
+	return { id, ...table }
+}
+
+function servedEntries<Id extends string, Value>(record: Readonly<Record<Id, Value | null>>): [Id, Value][] {
+	const entries: [Id, Value][] = []
+	for (const key in record) {
+		const value = record[key]
+		if (Object.hasOwn(record, key) && value !== null) entries.push([key, value])
+	}
+	return entries
+}

package/src/service/index.ts

@@ -0,0 +1,21 @@
+// @fabrika/app/service — the installation's own services only (IAM, Control, Operations). An application serves its
+// contract through `serve`; `@fabrika/check` refuses this import in one.
+
+export { dispatchRpcRequest } from '../rpc/dispatcher.js'
+export {
+	defineServiceContract,
+	type ServiceArtifact,
+	type ServiceContractBuilder,
+	type ServiceContractDeclaration,
+	ServiceContractError,
+	type ServiceEndpointOptions,
+	type ServiceEndpointSpec,
+} from './define.js'
+export {
+	serveService,
+	type ServeServiceOptions,
+	type ServiceHandler,
+	type ServiceHandlers,
+	ServiceHandlersError,
+	type ServiceRequest,
+} from './serve.js'

package/src/service/serve.ts

@@ -0,0 +1,99 @@
+// The dispatcher of a service contract: the service's one router, over the table the proxy decides from.
+
+import {
+	compileEndpointTable,
+	ENDPOINT_HEADER,
+	type InstallationEndpointRow,
+	parseEndpointHeader,
+	planEndpoint,
+	rawRequestTarget,
+	requirementDigest,
+} from '@fabrika/auth-core'
+import { defaultOnError, jsonResponse } from '../errors.js'
+import type { FetchService, RequestExecutionContext } from '../fetch.js'
+import type { ServiceArtifact } from './define.js'
+
+export interface ServiceRequest<Env> {
+	readonly request: Request
+	/** The `:name` segments of the selected path, percent-decoded. */
+	readonly params: Readonly<Record<string, string>>
+	readonly env: Env
+	readonly exec: RequestExecutionContext
+}
+
+export type ServiceHandler<Env> = (input: ServiceRequest<Env>) => Response | Promise<Response>
+
+/** One handler per declared row id, also for a row this composition left out; that one is never called. */
+export type ServiceHandlers<Id extends string, Env> = { readonly [K in Id]: ServiceHandler<Env> }
+
+export interface ServeServiceOptions<Env> {
+	/** Map a value a handler threw to a response. Defaults to the structural error mapping. */
+	readonly onError?: (error: unknown, request: Request, env: Env) => Response
+}
+
+export class ServiceHandlersError extends Error {
+	override readonly name = 'ServiceHandlersError'
+}
+
+/**
+ * Serve a service contract. Per request: a non-canonical path is a 400, a request no row selects a 404, a `service`
+ * row reached without the proxy's `X-Fabrika-Endpoint` for that row and its digest a 503; then the row's handler. A
+ * `protocol` or `health` row ignores the header, because the service authenticates it itself and it also arrives
+ * unfronted (ADR-0022 rule 5).
+ */
+export function serveService<Id extends string, Env>(
+	service: ServiceArtifact<Id>,
+	handlers: ServiceHandlers<Id, Env>,
+	options: ServeServiceOptions<Env> = {},
+): FetchService<Env> {
+	const table = compileEndpointTable<InstallationEndpointRow & { readonly id: Id }>(service)
+	const missing = service.endpoints.filter((row) => !Object.hasOwn(handlers, row.id)).map((row) => row.id)
+	if (missing.length > 0) {
+		throw new ServiceHandlersError(`service '${service.id}' has no handler for ${missing.map((id) => `'${id}'`).join(', ')}`)
+	}
+	const digests = new Map(service.endpoints.map((row) => [row.id, requirementDigest({ ...row, delegation: null })]))
+	const onError = options.onError ?? defaultOnError
+
+	return {
+		async fetch(request, env, exec) {
+			const plan = planEndpoint(table, request.method, rawRequestTarget(request.url).pathname)
+			if (plan.outcome === 'non-canonical') {
+				return jsonResponse({ error: { type: 'bad_request', message: 'The request path is not canonical' } }, 400)
+			}
+			if (plan.outcome === 'no-endpoint') {
+				return jsonResponse({ error: { type: 'not_found', message: 'Not found' } }, 404)
+			}
+			const row = plan.endpoint
+			if (row.kind === 'service' && !namesRow(request.headers.get(ENDPOINT_HEADER), row.id, digests.get(row.id))) {
+				console.error(`service '${service.id}': '${row.id}' was reached without the proxy's decision for its rules`)
+				return jsonResponse({ error: { type: 'unavailable', message: 'Service unavailable' } }, 503)
+			}
+			const params = decodeParams(plan.params)
+			if (params === null) {
+				return jsonResponse({ error: { type: 'bad_request', message: 'A path parameter does not decode' } }, 400)
+			}
+			try {
+				return await handlers[row.id]({ request, params, env, exec })
+			} catch (error) {
+				return onError(error, request, env)
+			}
+		},
+	}
+}
+
+function namesRow(header: string | null, id: string, digest: string | undefined): boolean {
+	const named = header === null ? null : parseEndpointHeader(header)
+	return named !== null && named.id === id && named.digest === digest
+}
+
+function decodeParams(raw: Readonly<Record<string, string>>): Readonly<Record<string, string>> | null {
+	const decoded: [string, string][] = []
+	for (const [name, value] of Object.entries(raw)) {
+		try {
+			decoded.push([name, decodeURIComponent(value)])
+		} catch {
+			return null
+		}
+	}
+	return Object.fromEntries(decoded)
+}

package/src/testing/caller.ts

@@ -0,0 +1,123 @@
+// Test callers: a principal of the test IAM with the permissions its grants resolve to, as IAM resolves them, and
+// the credential it presents.
+
+import type { PermissionEntry, PrincipalAffiliation } from '@fabrika/auth-core'
+import type { ActionOf, AnyContract, DimensionOf, RoleOf } from '../contract/define'
+
+/** `app` is the connector of another application: its key reaches only the exports that application consumes. */
+export type TestCallerKind = 'human' | 'machine' | 'link' | 'app'
+
+export interface TestScope<D extends string = string> {
+	readonly type: D
+	readonly value: string
+}
+
+/** An action, or a role whose actions IAM grants together; without a scope it is global. */
+export type TestGrant<C> =
+	| { readonly action: ActionOf<C>; readonly scope?: TestScope<DimensionOf<C>> }
+	| { readonly role: RoleOf<C>; readonly scope?: TestScope<DimensionOf<C>> }
+
+export interface TestCallerOptions {
+	/** Defaults to `human`. */
+	readonly kind?: TestCallerKind
+	/** How a human signs in: the IAM session (default) or a `px_` key bound to the person. Other kinds use a key. */
+	readonly via?: 'session' | 'key'
+	readonly id?: string
+	readonly label?: string
+	/** A human's address (`ctx.principal.email`), normalized as IAM stores it. Only a human has one. */
+	readonly email?: string
+	/**
+	 * Defaults to `internal`. An `external` human holds only roles the contract declares `external`, as IAM resolves it
+	 * (ADR-0051); the kit refuses any other grant for one.
+	 */
+	readonly affiliation?: PrincipalAffiliation
+	/**
+	 * An operator disabled the principal in IAM: a member directory lists and finds it with `disabled: true`, and the kit's
+	 * IAM signs no token for its session or key, so its requests are refused as IAM refuses a disabled principal's.
+	 */
+	readonly disabled?: boolean
+	/**
+	 * When the person last signed in to the application (unix seconds), as IAM records it at the handoff; absent, never.
+	 * A member directory answers it to a holder of `members.manage` only. Only a human signs in.
+	 */
+	readonly lastSignInAt?: number
+	/** The consuming application's id, for an `app` caller. */
+	readonly app?: string
+	/**
+	 * What a `link` caller's key is bound to: the link mount, and the object first, then each value containing it. A link
+	 * caller without one holds a key bound to nothing, which no procedure admits.
+	 */
+	readonly link?: TestLink
+}
+
+export interface TestLink {
+	readonly mount: string
+	readonly chain: readonly TestScope[]
+}
+
+interface TestCallerCredential {
+	/** The principal id, or the share key's credential id for a link. */
+	readonly id: string
+	/** `internal` for every caller but an `external` human. */
+	readonly affiliation: PrincipalAffiliation
+	/** `true` for a principal an operator disabled; `false` for every other caller, a link holder included. */
+	readonly disabled: boolean
+	/** A human's last sign-in to the application (`TestCallerOptions.lastSignInAt`); `null` for one that never did and every other caller. */
+	readonly lastSignInAt: number | null
+	readonly perms: readonly PermissionEntry[]
+	/** The `px_` key a key caller presents as a bearer; `null` for a session. */
+	readonly key: string | null
+	/** The `Cookie` header a signed-in browser sends; `null` for a key caller. */
+	readonly cookie: string | null
+}
+
+/** A person, a script or another application's connector: a principal with a label. */
+export interface LabelledTestCaller extends TestCallerCredential {
+	readonly kind: Exclude<TestCallerKind, 'link'>
+	/** The consuming application of an `app` caller, `null` for every other kind. */
+	readonly app: string | null
+	readonly link: null
+	readonly label: string
+	/** A human's normalized address, which its token carries; `null` for a script and a connector. */
+	readonly email: string | null
+}
+
+/** A person, whose token carries its address: `ctx.principal.email` of its requests. */
+export interface PersonTestCaller extends LabelledTestCaller {
+	readonly kind: 'human'
+	readonly email: string
+}
+
+/** The holder of a share link: an anonymous key, which carries no label. */
+export interface LinkTestCaller extends TestCallerCredential {
+	readonly kind: 'link'
+	readonly app: null
+	/** The link mount and chain the key is bound to; `null` for a key bound to nothing. */
+	readonly link: TestLink | null
+	readonly label: null
+	readonly email: null
+}
+
+export type TestCaller = LabelledTestCaller | LinkTestCaller
+
+/** The permissions `grants` resolve to: a role becomes each of its actions in the role's scope. */
+export function resolveGrants<C extends AnyContract>(contract: C, grants: readonly TestGrant<C>[]): PermissionEntry[] {
+	const { actions, roles } = contract.vocabulary
+	const scopeOf = (scope: TestScope | undefined) => (scope === undefined ? null : { type: scope.type, value: scope.value })
+	return grants.flatMap((grant): PermissionEntry[] => {
+		if ('action' in grant) {
+			if (!Object.hasOwn(actions, grant.action)) {
+				throw new Error(`'${grant.action}' is not an action of the contract`)
+			}
+			return [{ action: grant.action, scope: scopeOf(grant.scope), source: 'grant' }]
+		}
+		const role = Object.hasOwn(roles, grant.role) ? roles[grant.role] : undefined
+		if (role === undefined) {
+			throw new Error(`'${grant.role}' is not a role of the contract`)
+		}
+		if (role.member !== undefined && grant.scope?.type !== role.member.scope) {
+			throw new Error(`'${grant.role}' is a membership role: grant it in one ${role.member.scope} (scope: { type: '${role.member.scope}', value })`)
+		}
+		return role.grants.map((action) => ({ action, scope: scopeOf(grant.scope), source: 'grant' }))
+	})
+}

package/src/testing/challenge.ts

@@ -0,0 +1,10 @@
+// A stand-in for a form challenge's provider, for a test kit and for `fabrika app dev`.
+
+import type { ChallengeFetch } from '../implement/challenge'
+
+/** The token Turnstile's always-passing test widget (site key `1x00000000000000000000AA`) hands out every time. */
+export const TURNSTILE_TEST_TOKEN = 'XXXX.DUMMY.TOKEN.XXXX'
+
+/** Turnstile's siteverify that passes every token: a fresh answer for the host and the form the check expects. */
+export const passingChallenge: ChallengeFetch = (_request, check) =>
+	Promise.resolve(Response.json({ success: true, challenge_ts: new Date().toISOString(), hostname: check.hostname, action: check.action }))

package/src/testing/dev.ts

@@ -0,0 +1,99 @@
+// The kit `fabrika app dev` previews an application through, and the types of the seed module it runs first.
+
+import type { AnyContract, DimensionOf } from '../contract/define'
+import type { ContractImplementation } from '../implement/implement'
+import type { PersonTestCaller, TestCaller } from './caller'
+import { passingChallenge, TURNSTILE_TEST_TOKEN } from './challenge'
+import { bootTestKit, type TestKit, type TestKitOptions } from './kit'
+import type { SentInvitation, TestMembership } from './membership'
+
+/** Someone the author clicks through the application as: a person the seed made with `dev.testCaller`. */
+export interface DevPersona {
+	/** Shown on the picker's card and in the toolbar, unique among the personas: `Petra`. */
+	readonly name: string
+	/** One short line of who this is: `Staff of the design workspace`. */
+	readonly description?: string
+	readonly caller: PersonTestCaller
+}
+
+/** A page a link holder opens: a link the seed issued through the application's own endpoint. */
+export interface DevLink {
+	readonly title: string
+	readonly description?: string
+	/** The URL the application answered, a path of its origin: `/s/#px_…`. */
+	readonly url: string
+}
+
+/** A scope value the seed made, with the name a person knows it by: `{ value: 'w1', label: 'Design team' }`. */
+export interface DevScopeValue {
+	readonly value: string
+	readonly label: string
+}
+
+/** What a seed answers; every part is optional. */
+export interface DevSeedResult<C extends AnyContract> {
+	readonly personas?: readonly DevPersona[]
+	readonly links?: readonly DevLink[]
+	/** The values of each dimension the seed made, which the picker offers for a membership role. */
+	readonly scopes?: { readonly [D in DimensionOf<C>]?: readonly DevScopeValue[] }
+}
+
+/** The origin `fabrika app dev` captures every request to: an outside provider's stand-in, named by its path. */
+export const DEV_OUTBOX_ORIGIN = 'https://outbox.invalid'
+
+/** A request the application sent to `DEV_OUTBOX_ORIGIN` under `fabrika app dev`: its body, never its headers. */
+export interface DevOutboxMessage {
+	readonly id: number
+	readonly method: string
+	/** The path it was sent to: `/mail`. */
+	readonly path: string
+	readonly contentType: string | null
+	readonly body: string
+}
+
+/** What `fabrika app dev` stands in for outside the application, for the seed to read. */
+export interface DevOutside {
+	/** Every request sent to `DEV_OUTBOX_ORIGIN` so far, oldest first. */
+	outbox(): readonly DevOutboxMessage[]
+}
+
+/**
+ * The default export of `dev/seed.ts`: it receives the application's test kit, the API its tests use, writes through the
+ * endpoints, and answers who and what the picker offers. `outside` reads what the application sent to the dev outbox.
+ */
+export type DevSeed<C extends AnyContract> = (dev: TestKit<C>, outside: DevOutside) => Promise<DevSeedResult<C>> | DevSeedResult<C>
+
+export interface DevKit<C extends AnyContract> {
+	readonly kit: TestKit<C>
+	/** The person `value` is when this kit made it; `undefined` for any other value. */
+	personOf(value: unknown): PersonTestCaller | undefined
+	/** The roles a caller of this kit holds now: its grants, with what the application assigned and revoked through IAM. */
+	membershipsOf(caller: TestCaller): readonly TestMembership[]
+	/** The invitation e-mails the stand-in IAM sent, in the order it first sent them. */
+	invitations(): readonly SentInvitation[]
+}
+
+const isPerson = (caller: TestCaller): caller is PersonTestCaller => caller.kind === 'human' && caller.email !== null
+
+/**
+ * The test kit of `app` with its stand-in IAM, and what `fabrika app dev` shows of it. A form's challenge passes
+ * (`passingChallenge`) unless `options.challengeFetch` answers it, and admits the test widget's token
+ * (`TURNSTILE_TEST_TOKEN`) at every submission; any other token is single use, as deployed.
+ */
+export function devKit<C extends AnyContract>(app: ContractImplementation<C>, options: Omit<TestKitOptions, 'membership'> = {}): DevKit<C> {
+	const { kit, standIn, callerOf } = bootTestKit(app, { challengeFetch: passingChallenge, ...options }, {
+		repeatableChallengeToken: TURNSTILE_TEST_TOKEN,
+	})
+	if (standIn === null) {
+		throw new Error('a kit without its own membership transport stands in for IAM')
+	}
+	return Object.freeze({
+		kit,
+		personOf(value: unknown): PersonTestCaller | undefined {
+			const caller = callerOf(value)
+			return caller !== undefined && isPerson(caller) ? caller : undefined
+		},
+		membershipsOf: (caller: TestCaller) => standIn.membershipsOf(caller),
+		invitations: () => standIn.invitations(),
+	})
+}