@fabrika/app 0.4.0 → 0.4.2

package/src/testing/kit.ts

@@ -38,12 +38,13 @@ import { diskAssets } from '../disk-assets'
 import type { RequestExecutionContext } from '../fetch'
 import type { FILE_SWEEP_JOB } from '../files/collections'
 import type { FILE_SCAN_JOB, FileScanner } from '../files/scan'
-import { boot, type ContractApp } from '../implement/boot'
+import { boot, type BootOptions, type ContractApp } from '../implement/boot'
 import type { ChallengeFetch } from '../implement/challenge'
 import { type ConnectFetch, connectVariables } from '../implement/connect'
 import type { SpaAssets } from '../implement/dispatch'
 import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement'
 import type { WorkloadKindOf, WorkloadTokenSource } from '../implement/workload'
+import type { HandlerErrorSink } from '../jobs/runner'
 import type { JobRunOptions, JobRunResult } from '../jobs/runner'
 import {
 	type LabelledTestCaller,
@@ -55,7 +56,15 @@ import {
 	type TestGrant,
 	type TestScope,
 } from './caller'
-import { credentialCallers, type KitMembership, kitMembership, type MintedToken, type TestMembership } from './membership'
+import {
+	credentialCallers,
+	type JobCredential,
+	type KitJobCaller,
+	type KitMembership,
+	kitMembership,
+	type MintedToken,
+	type TestMembership,
+} from './membership'
 import { endpointProxy } from './proxy'
 
 export const TEST_ISSUER = 'https://iam.test'
@@ -95,6 +104,8 @@ export interface TestKitOptions {
 	readonly connect?: Readonly<Record<string, TestConnection>>
 	/** What answers a form's challenge verification in place of the provider: a stand-in for its siteverify. */
 	readonly challengeFetch?: ChallengeFetch
+	/** What a job's handler threw, shown on the developer's own machine: `fabrika app dev` sets it, a test need not. */
+	readonly revealHandlerErrors?: HandlerErrorSink
 }
 
 export interface TestConnection {
@@ -205,7 +216,14 @@ export interface BootedTestKit<C extends AnyContract> {
 	callerOf(value: unknown): TestCaller | undefined
 }
 
-export function bootTestKit<C extends AnyContract>(app: ContractImplementation<C>, options: TestKitOptions): BootedTestKit<C> {
+/** What only `fabrika app dev`'s kit boots with, never a test's. */
+export type DevBootOptions = Pick<BootOptions, 'repeatableChallengeToken'>
+
+export function bootTestKit<C extends AnyContract>(
+	app: ContractImplementation<C>,
+	options: TestKitOptions,
+	dev: DevBootOptions = {},
+): BootedTestKit<C> {
 	refuseInProduction('@fabrika/app/testing')
 	const name = app.contract.vocabulary.app
 	const appId = `${name}@${TEST_ENVIRONMENT}`
@@ -231,6 +249,12 @@ export function bootTestKit<C extends AnyContract>(app: ContractImplementation<C
 	// The kit stands in for Control too: every job and webhook gets a key, which its stand-in IAM signs the declared actions for.
 	const workloadVariables: Record<string, string> = {}
 	const workloadsByKey = new Map<string, { readonly kind: WorkloadKindOf; readonly name: string; readonly actions: readonly string[] }>()
+	// A job's key and the tokens signed for it are its credential at the stand-in IAM's link operations, as at IAM's.
+	const jobCredentials = new Map<string, JobCredential>()
+	const jobCallerOf = (name: string): KitJobCaller | undefined => {
+		const job = Object.hasOwn(artifact.jobs, name) ? artifact.jobs[name] : undefined
+		return job === undefined ? undefined : { id: `job-${name}`, actions: job.actions, issues: artifact.declared?.[`job:${name}`]?.issues ?? null }
+	}
 	const declaredWorkloads = [
 		...Object.entries(artifact.jobs).map(([workload, job]) => ({ kind: 'job' as const, name: workload, actions: job.actions })),
 		...Object.entries(artifact.mounts).flatMap(([workload, mount]) =>
@@ -241,6 +265,8 @@ export function bootTestKit<C extends AnyContract>(app: ContractImplementation<C
 		const key = `${API_KEY_PREFIX}test_${crypto.randomUUID().replaceAll('-', '')}`
 		workloadVariables[workloadKeyVariable(workload.kind, workload.name)] = key
 		workloadsByKey.set(key, workload)
+		const job = workload.kind === 'job' ? jobCallerOf(workload.name) : undefined
+		if (job !== undefined) jobCredentials.set(key, { job, expiresAt: null })
 	}
 	const workloadTokens: WorkloadTokenSource = {
 		async exchange({ app: audience, key }) {
@@ -261,18 +287,23 @@ export function bootTestKit<C extends AnyContract>(app: ContractImplementation<C
 				expiresAt: now + TOKEN_TTL_SECONDS,
 			})
 			const { privateKey } = await signing
-			return {
-				ok: true,
-				token: await new SignJWT({ ...claims }).setProtectedHeader({ alg: TOKEN_ALG, kid: KEY_ID }).sign(privateKey),
-				expiresAt: claims.exp,
-			}
+			const token = await new SignJWT({ ...claims }).setProtectedHeader({ alg: TOKEN_ALG, kid: KEY_ID }).sign(privateKey)
+			const job = jobCredentials.get(key)?.job
+			if (job !== undefined) jobCredentials.set(token, { job, expiresAt: claims.exp })
+			return { ok: true, token, expiresAt: claims.exp }
 		},
 	}
 	const byKey = new Map<string, TestCaller>()
 	const bySession = new Map<string, TestCaller>()
 	const byToken = new Map<string, MintedToken>()
 	const memberships = new Map<TestCaller, readonly TestMembership[]>()
-	const directoryCallers = credentialCallers(appId, byKey, byToken, () => [...memberships].map(([caller, held]) => ({ caller, memberships: held })))
+	const directoryCallers = credentialCallers(
+		appId,
+		byKey,
+		byToken,
+		() => [...memberships].map(([caller, held]) => ({ caller, memberships: held })),
+		jobCredentials,
+	)
 	// The stand-in answers the member directory from the kit's own callers and the writes under IAM's rules; it also
 	// issues the proxy's delegation grants.
 	const standIn = options.membership === undefined ? kitMembership(artifact, directoryCallers) : null
@@ -295,6 +326,8 @@ export function bootTestKit<C extends AnyContract>(app: ContractImplementation<C
 		files: options.files,
 		...(options.scanner === undefined ? {} : { scanner: options.scanner }),
 		...(options.challengeFetch === undefined ? {} : { challengeFetch: options.challengeFetch }),
+		...dev,
+		...(options.revealHandlerErrors === undefined ? {} : { revealHandlerErrors: options.revealHandlerErrors }),
 		membership,
 		connectBindings,
 		workloadTokens,

package/src/testing/membership.ts

@@ -63,10 +63,25 @@ export interface DirectoryCallers {
 	 * none for a credential of another application or an expired token.
 	 */
 	byCredential(app: string, credential: string): TestCaller | undefined
+	/** The job a link operation's credential (its workload key or token) belongs to, as IAM resolves it for `app`. */
+	jobByCredential(app: string, credential: string): KitJobCaller | undefined
 	/** Every caller with its role grants. */
 	all(): readonly { readonly caller: TestCaller; readonly memberships: readonly TestMembership[] }[]
 }
 
+/** A job's principal, as IAM holds it to its declaration: its actions app-wide, and the one link mount it issues. */
+export interface KitJobCaller {
+	readonly id: string
+	readonly actions: readonly string[]
+	readonly issues: string | null
+}
+
+/** A job's workload key (`expiresAt: null`) or a token the kit signed for it. */
+export interface JobCredential {
+	readonly job: KitJobCaller
+	readonly expiresAt: number | null
+}
+
 /** A write `kitMembership` allowed, by the principal that asked; the credential and the delegation grant are left out. */
 export type AskedWrite =
 	| { readonly operation: 'createScope'; readonly principalId: string; readonly scope: Scope; readonly role: string }
@@ -181,6 +196,7 @@ export function credentialCallers(
 	keys: ReadonlyMap<string, TestCaller>,
 	tokens: ReadonlyMap<string, MintedToken>,
 	memberships: () => ReturnType<DirectoryCallers['all']>,
+	jobs: ReadonlyMap<string, JobCredential> = new Map(),
 ): DirectoryCallers {
 	return {
 		byCredential(audience, credential) {
@@ -189,6 +205,10 @@ export function credentialCallers(
 			if (minted === undefined) return keys.get(credential)
 			return minted.expiresAt > now() ? minted.caller : undefined
 		},
+		jobByCredential(audience, credential) {
+			const held = audience === app ? jobs.get(credential) : undefined
+			return held !== undefined && (held.expiresAt === null || held.expiresAt > now()) ? held.job : undefined
+		},
 		all: memberships,
 	}
 }
@@ -221,6 +241,13 @@ function memberCaller(callers: DirectoryCallers, input: MembershipCaller, userOn
 
 const isFailure = (outcome: LabelledTestCaller | MembershipFailure): outcome is MembershipFailure => 'ok' in outcome
 
+/** Who asks for a link operation: a member caller (`issues: null`), or a job and the mount it issues. */
+interface LinkCaller {
+	readonly id: string
+	readonly perms: readonly PermissionEntry[]
+	readonly issues: string | null
+}
+
 function dimensionOf(artifact: ContractArtifact, type: string) {
 	return Object.hasOwn(artifact.dimensions, type) ? artifact.dimensions[type] : undefined
 }
@@ -416,6 +443,7 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 	const links = new Map<string, KitLink>()
 	const live: DirectoryCallers = {
 		byCredential: (app, credential) => callers.byCredential(app, credential),
+		jobByCredential: (app, credential) => callers.jobByCredential(app, credential),
 		all: () => callers.all().map(({ caller, memberships }) => ({ caller, memberships: changes.heldBy(caller.id, memberships) })),
 	}
 
@@ -638,10 +666,28 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 		return expected === null ? null : `the link chain stops before '${expected}'`
 	}
 
-	/** A share link, for a holder of the mount's `issuedBy` and of every action it grants on some value of the chain. */
-	const issueLink = (input: IssueLinkInput): IssueLinkResult => {
+	/**
+	 * The caller of a link operation, as IAM resolves it: a member caller, or a job that declares `issues`, which holds
+	 * its declared actions app-wide.
+	 */
+	const linkCaller = (input: MembershipCaller): LinkCaller | MembershipFailure => {
+		const job = input.credential === null ? undefined : callers.jobByCredential(input.app, input.credential)
+		if (job !== undefined) {
+			if (job.issues === null) return NOT_ALLOWED
+			return { id: job.id, perms: job.actions.map((action) => ({ action, scope: null, source: 'grant' })), issues: job.issues }
+		}
 		const caller = memberCaller(callers, input, false)
-		if (isFailure(caller)) return caller
+		return isFailure(caller) ? caller : { id: caller.id, perms: permsOf(caller), issues: null }
+	}
+
+	/**
+	 * A share link, for a holder of the mount's `issuedBy` and of every action it grants on some value of the chain; a
+	 * job issues only for the mount it declares.
+	 */
+	const issueLink = (input: IssueLinkInput): IssueLinkResult => {
+		const caller = linkCaller(input)
+		if ('ok' in caller) return caller
+		if (caller.issues !== null && caller.issues !== input.mount) return NOT_ALLOWED
 		const mount = Object.hasOwn(artifact.mounts, input.mount) ? artifact.mounts[input.mount] : undefined
 		if (mount?.kind !== 'link') return invalid(`unknown link mount '${input.mount}'`)
 		const problem = chainProblem(mount.dimension, input.chain)
@@ -649,7 +695,7 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 		if (!Number.isSafeInteger(input.days) || input.days < 1 || input.days > mount.maxDays) {
 			return invalid(`a link of '${input.mount}' lives 1 to ${mount.maxDays} days`)
 		}
-		const perms = [...permsOf(caller)]
+		const perms = [...caller.perms]
 		const heldOnChain = (action: string): boolean => input.chain.some((scope) => permits(perms, action, scope))
 		if (!heldOnChain(mount.issuedBy) || !mount.grants.every(heldOnChain)) return NOT_ALLOWED
 		const id = `link-${randomId()}`
@@ -659,15 +705,19 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 		return { ok: true, key, id, expiresAt: now() + input.days * DAY_SECONDS }
 	}
 
-	/** A link this stand-in issued, by its issuer or a holder of `members.manage` on a value of its chain. */
+	/**
+	 * A link this stand-in issued, by its issuer or a holder of `members.manage` on a value of its chain; a job revokes
+	 * only a link it issued, of the mount it declares.
+	 */
 	const revokeLink = (input: RevokeLinkInput): RevokeLinkResult => {
-		const caller = memberCaller(callers, input, false)
-		if (isFailure(caller)) return caller
+		const caller = linkCaller(input)
+		if ('ok' in caller) return caller
 		const link = links.get(input.id)
 		if (link === undefined) return NOT_FOUND
-		const manager = link.chain.some((scope) => {
+		if (caller.issues !== null && (link.issuer !== caller.id || link.mount !== caller.issues)) return NOT_ALLOWED
+		const manager = caller.issues === null && link.chain.some((scope) => {
 			const members = dimensionOf(artifact, scope.type)?.members
-			return members !== null && members !== undefined && permits([...permsOf(caller)], members.manage, scope)
+			return members !== null && members !== undefined && permits([...caller.perms], members.manage, scope)
 		})
 		if (link.issuer !== caller.id && !manager) return NOT_ALLOWED
 		links.set(link.id, { ...link, revoked: true })