@fabrika/app 0.3.2 → 0.4.0

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/dev.ts

@@ -0,0 +1,73 @@
+// 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 { 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 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.
+ */
+export type DevSeed<C extends AnyContract> = (dev: TestKit<C>) => 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. */
+export function devKit<C extends AnyContract>(app: ContractImplementation<C>, options: Omit<TestKitOptions, 'membership'> = {}): DevKit<C> {
+	const { kit, standIn, callerOf } = bootTestKit(app, options)
+	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(),
+	})
+}