@owlmeans/client-auth 0.1.18-rc.9 → 0.1.18

package/tests/land.spec.ts

@@ -0,0 +1,292 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { makeTestContext } from './context.js'
+import { makeFixtureKeyPair } from '@owlmeans/test-auth'
+import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
+import { AuthroizationType, AuthRole, DISPATCHER, type Auth } from '@owlmeans/auth'
+import { HOME, type BasicContext, type BasicConfig } from '@owlmeans/context'
+import { createStaticResource } from '@owlmeans/static-resource'
+import type { Resource } from '@owlmeans/resource'
+import { FLOW_STATE, RESUME_FLOW, type SuspendedLandingRecord } from '@owlmeans/client-flow'
+import { DEFAULT_ALIAS as AUTH_ALIAS } from '../src/consts.js'
+import type { AuthService } from '@owlmeans/auth-common'
+import { appendLogin } from '../src/login/service.js'
+import { makeLoginLandingHelper } from '../src/login/land.js'
+import { LOGIN_LANDED_STORAGE } from '../src/login/consts.js'
+import type { LoginLandingHook, LoginService, LoginStep } from '../src/login/types.js'
+
+/**
+ * A hand-written `window.localStorage`, not jsdom — `land.ts` reads exactly two keys through
+ * `try`/`catch`, and a real DOM would prove a fixture behaves rather than that the module does.
+ * Mirrors `web-client/tests/surrogate.spec.ts`'s own `stubWindow` idiom.
+ */
+const stubStorage = (): void => {
+  const store = new Map<string, string>()
+  ;(globalThis as unknown as { window: unknown }).window = {
+    localStorage: {
+      getItem: (key: string) => (store.has(key) ? store.get(key)! : null),
+      setItem: (key: string, value: string) => { store.set(key, value) },
+      removeItem: (key: string) => { store.delete(key) },
+    },
+  }
+}
+
+afterEach(() => {
+  delete (globalThis as { window?: unknown }).window
+})
+
+/** A validly-signed bearer, exactly as `server-auth` would issue one. */
+const makeBearer = async (auth: Partial<Auth>): Promise<string> => {
+  const appKP = makeFixtureKeyPair('client-auth-land-test-key')
+  const fullAuth: Auth = {
+    token: 'nonce-123', userId: 'user-1', scopes: ['*'], role: AuthRole.User,
+    type: AuthroizationType.Ed25519BasicToken, source: 'test-service', isUser: true,
+    createdAt: new Date(), ...auth,
+  }
+  const signed = await makeEnvelopeModel<Auth>(AuthroizationType.Ed25519BasicToken)
+    .send(fullAuth, null).sign(appKP, EnvelopeKind.Token)
+
+  return `${AuthroizationType.Ed25519BasicToken.toUpperCase()} ${signed}`
+}
+
+const bootstrap = async (opts?: {
+  authenticated?: boolean, withFlowState?: boolean
+}): Promise<[BasicContext<BasicConfig>, LoginService]> => {
+  const context = makeTestContext()
+  if (opts?.withFlowState) {
+    context.registerResource(
+      createStaticResource<SuspendedLandingRecord>(FLOW_STATE, 'client-auth-land-tests')
+    )
+  }
+  context.configure()
+  await context.init()
+
+  if (opts?.authenticated) {
+    const authService = context.service<AuthService>(AUTH_ALIAS)
+    await authService.update(await makeBearer({ userId: 'land-test-user' }))
+  }
+
+  const contextual = appendLogin(context)
+
+  return [context, contextual.login()]
+}
+
+const step = (over: Partial<LoginStep> & { alias: string, entrypoint: string }): LoginStep => ({
+  pending: async () => false, ...over,
+})
+
+/** Grant a fake alias existence without building a real entrypoint/route graph. */
+const allowEntrypoints = (context: BasicContext<BasicConfig>, ...aliases: string[]): void => {
+  (context as unknown as { hasEntrypoint: (alias: string) => boolean }).hasEntrypoint =
+    alias => aliases.includes(alias)
+}
+
+describe('continueLogin — no steps registered', () => {
+  test('falls through to a suspended flow, then HOME', async () => {
+    const [context] = await bootstrap({ authenticated: true })
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({ alias: HOME })
+  })
+})
+
+describe('continueLogin — steps', () => {
+  test('a pending step lands there, and a suspended landing is NOT consumed', async () => {
+    stubStorage()
+    const [context, login] = await bootstrap({ authenticated: true, withFlowState: true })
+    allowEntrypoints(context, 'step-screen')
+
+    const resource = context.resource<Resource<SuspendedLandingRecord>>(FLOW_STATE)
+    await resource.save({
+      id: RESUME_FLOW, entrypoint: 'suspended-screen', query: { ref: 'abc' },
+      expiresAt: Date.now() + 60_000,
+    })
+
+    login.registerStep(step({
+      alias: 'consent', entrypoint: 'step-screen', pending: async () => true,
+      query: () => ({ from: 'test' }),
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({
+      alias: 'step-screen', query: { from: 'test' }, step: 'consent',
+    })
+    // The suspended landing is still there — a later step, or the eventual fallback, still needs it.
+    expect(await resource.load(RESUME_FLOW)).not.toBeNull()
+  })
+
+  test('a step whose `pending` throws is treated as not pending — fail open', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    allowEntrypoints(context, 'broken-screen')
+
+    login.registerStep(step({
+      alias: 'broken', entrypoint: 'broken-screen',
+      pending: async () => { throw new Error('boom') },
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({ alias: HOME })
+  })
+
+  test('a step whose `pending` never resolves is treated as not pending after the timeout', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    allowEntrypoints(context, 'hanging-screen')
+
+    login.registerStep(step({
+      alias: 'hanging', entrypoint: 'hanging-screen',
+      pending: () => new Promise<boolean>(() => { /* never settles */ }),
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin({ stepTimeout: 20 })).toEqual({ alias: HOME })
+  })
+
+  test('a step whose entrypoint is unresolvable is skipped, never throws', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    let called = false
+
+    login.registerStep(step({
+      alias: 'unbound', entrypoint: 'nowhere', pending: async () => { called = true; return true },
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({ alias: HOME })
+    expect(called).toBe(false)
+  })
+
+  test('`after` skips every step up to and including that alias', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    allowEntrypoints(context, 'a-screen', 'b-screen')
+
+    login.registerStep(step({ alias: 'a', entrypoint: 'a-screen', priority: 20, pending: async () => true }))
+    login.registerStep(step({ alias: 'b', entrypoint: 'b-screen', priority: 10, pending: async () => true }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({ alias: 'a-screen', query: undefined, step: 'a' })
+    expect(await makeLoginLandingHelper(context).continueLogin({ after: 'a' }))
+      .toEqual({ alias: 'b-screen', query: undefined, step: 'b' })
+  })
+
+  test('an unauthenticated caller with an explicit alias still gets that alias', async () => {
+    const [context] = await bootstrap()
+
+    expect(await makeLoginLandingHelper(context).continueLogin({
+      fallback: { alias: 'explicit-alias' }, resume: false,
+    })).toEqual({ alias: 'explicit-alias' })
+  })
+})
+
+describe('continueLogin — a `required` step', () => {
+  test('a `required` step whose `pending` throws is treated as PENDING — fail closed', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    allowEntrypoints(context, 'required-screen')
+
+    login.registerStep(step({
+      alias: 'required-broken', entrypoint: 'required-screen', required: true,
+      pending: async () => { throw new Error('boom') },
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({
+      alias: 'required-screen', query: undefined, step: 'required-broken',
+    })
+  })
+
+  test('a `required` step whose `pending` never resolves is treated as PENDING after the timeout', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    allowEntrypoints(context, 'required-hanging-screen')
+
+    login.registerStep(step({
+      alias: 'required-hanging', entrypoint: 'required-hanging-screen', required: true,
+      pending: () => new Promise<boolean>(() => { /* never settles */ }),
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin({ stepTimeout: 20 })).toEqual({
+      alias: 'required-hanging-screen', query: undefined, step: 'required-hanging',
+    })
+  })
+
+  test('a `required` but UNBOUND step is still skipped, never blocks', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    let called = false
+
+    login.registerStep(step({
+      alias: 'required-unbound', entrypoint: 'nowhere', required: true,
+      pending: async () => { called = true; return true },
+    }))
+
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({ alias: HOME })
+    expect(called).toBe(false)
+  })
+
+  test('a `required` step that answers false, or true, still behaves ordinarily', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    allowEntrypoints(context, 'required-screen')
+
+    login.registerStep(step({
+      alias: 'required-ok', entrypoint: 'required-screen', required: true, pending: async () => false,
+    }))
+    expect(await makeLoginLandingHelper(context).continueLogin()).toEqual({ alias: HOME })
+  })
+})
+
+describe('landAfterLogin — the surrogate short circuit', () => {
+  test('returns DISPATCHER immediately; no step or hook ever runs', async () => {
+    const [context, login] = await bootstrap({ authenticated: true })
+    login.env = () => ({ hasWindow: true, embedded: true, surrogate: true, hasOpener: true })
+
+    let stepCalled = false
+    let hookCalled = false
+    login.registerStep(step({
+      alias: 'never', entrypoint: 'never-screen', pending: async () => { stepCalled = true; return true },
+    }))
+    login.onLanded({ alias: 'never', landed: async () => { hookCalled = true } })
+
+    expect(await makeLoginLandingHelper(context).landAfterLogin()).toEqual({ alias: DISPATCHER })
+    expect(stepCalled).toBe(false)
+    expect(hookCalled).toBe(false)
+  })
+})
+
+describe('landAfterLogin — landing hooks', () => {
+  const hook = (over: Partial<LoginLandingHook> & { alias: string }): LoginLandingHook => ({
+    landed: async () => { }, ...over,
+  })
+
+  test('run exactly once per distinct token, in priority order, each swallowed on error', async () => {
+    stubStorage()
+    const [context, login] = await bootstrap({ authenticated: true })
+
+    const order: string[] = []
+    login.onLanded(hook({ alias: 'low', priority: 0, landed: async () => { order.push('low') } }))
+    login.onLanded(hook({
+      alias: 'high', priority: 10, landed: async () => { order.push('high'); throw new Error('boom') },
+    }))
+
+    await makeLoginLandingHelper(context).landAfterLogin()
+    expect(order).toEqual(['high', 'low'])
+
+    // Same token again — neither hook runs a second time.
+    await makeLoginLandingHelper(context).landAfterLogin()
+    expect(order).toEqual(['high', 'low'])
+  })
+
+  test('a distinct token runs the hooks again', async () => {
+    stubStorage()
+    const [context, login] = await bootstrap({ authenticated: true })
+
+    let count = 0
+    login.onLanded(hook({ alias: 'counter', landed: async () => { count += 1 } }))
+
+    await makeLoginLandingHelper(context).landAfterLogin()
+    expect(count).toBe(1)
+
+    const authService = context.service<AuthService>(AUTH_ALIAS)
+    await authService.update(await makeBearer({ userId: 'a-different-user' }))
+
+    await makeLoginLandingHelper(context).landAfterLogin()
+    expect(count).toBe(2)
+  })
+
+  test('storage records the raw token, not a digest, under LOGIN_LANDED_STORAGE', async () => {
+    stubStorage()
+    const [context] = await bootstrap({ authenticated: true })
+    const authService = context.service<AuthService>(AUTH_ALIAS)
+
+    await makeLoginLandingHelper(context).landAfterLogin()
+
+    expect(window.localStorage.getItem(LOGIN_LANDED_STORAGE)).toBe(authService.token as string)
+  })
+})

package/tests/login.spec.ts

@@ -0,0 +1,332 @@
+import { describe, test, expect } from 'bun:test'
+import { makeTestContext } from './context.js'
+import { appendLogin, makeLoginService } from '../src/login/service.js'
+import { loginMethodsHelper } from '../src/login/methods.js'
+import { resolveCredit } from '../src/login/credit.js'
+import { pluginMethodSource } from '../src/manager/plugins/methods.js'
+import { authPluginHelper } from '../src/manager/plugins/registry.js'
+import type { AuthenticationPlugin } from '../src/manager/plugins/types.js'
+import { loginResumeHelper } from '../src/login/resume.js'
+import { ResumeAction, LoginOutcome } from '../src/login/consts.js'
+import type {
+  LoginEnv, LoginMethod, LoginMethodContext, LoginPlugin, LoginService,
+} from '../src/login/types.js'
+import type { BasicContext, BasicConfig } from '@owlmeans/context'
+
+/**
+ * A hand-written environment descriptor.
+ *
+ * `LoginEnv` exists precisely so a plugin's decisions can be exercised without a DOM — a stubbed
+ * `window` would prove that the stub behaves, not that the cascade does.
+ */
+const env = (over?: Partial<LoginEnv>): LoginEnv => ({
+  hasWindow: true, embedded: false, surrogate: false, hasOpener: false, ...over,
+})
+
+const stubPlugin = (over: Partial<LoginPlugin> & { alias: string }): LoginPlugin => ({
+  begin: async () => LoginOutcome.Passed,
+  authorize: async () => LoginOutcome.Passed,
+  complete: async () => LoginOutcome.Passed,
+  ...over,
+})
+
+const bootstrap = (): [BasicContext<BasicConfig>, LoginService] => {
+  const context = makeTestContext()
+  const contextual = appendLogin(context)
+
+  return [context, contextual.login()]
+}
+
+const methodCtx = (context: BasicContext<BasicConfig>, over?: Partial<LoginEnv>): LoginMethodContext =>
+  ({ context, env: env(over) })
+
+const method = (over: Partial<LoginMethod> & { id: string }): LoginMethod => ({
+  start: async () => LoginOutcome.Passed, ...over,
+})
+
+describe('login plugin host', () => {
+  test('the cascade picks the highest-priority plugin whose match holds', () => {
+    const service = makeLoginService()
+    service.registerPlugin(stubPlugin({ alias: 'default', priority: 0, match: () => true }))
+    service.registerPlugin(stubPlugin({
+      alias: 'framed', priority: 100, match: candidate => candidate.embedded,
+    }))
+
+    expect(service.plugin(env()).alias).toBe('default')
+    expect(service.plugin(env({ embedded: true })).alias).toBe('framed')
+  })
+
+  test('a plugin with no resume yields Passed, so an ordinary tab is untouched', async () => {
+    const [, service] = bootstrap()
+    service.registerPlugin(stubPlugin({ alias: 'plain', match: () => true }))
+
+    expect(await service.resume('a-token')).toBe(LoginOutcome.Passed)
+  })
+
+  test('a plugin with a resume is asked instead', async () => {
+    const [, service] = bootstrap()
+    service.registerPlugin(stubPlugin({
+      alias: 'framed', match: () => true, resume: async () => LoginOutcome.Handled,
+    }))
+
+    expect(await service.resume('a-token')).toBe(LoginOutcome.Handled)
+  })
+
+  test('a refusing precondition stops the flow before any plugin runs', async () => {
+    const [, service] = bootstrap()
+    let started = false
+    service.registerPlugin(stubPlugin({
+      alias: 'plain', match: () => true,
+      begin: async () => { started = true; return LoginOutcome.Handled },
+    }))
+    service.registerPrecondition({ alias: 'refuse', check: () => false })
+
+    expect(await service.begin({ url: '/dispatcher' })).toBe(LoginOutcome.Gesture)
+    expect(started).toBe(false)
+  })
+
+  test('a passing precondition lets the plugin run', async () => {
+    const [, service] = bootstrap()
+    service.registerPlugin(stubPlugin({
+      alias: 'plain', match: () => true, begin: async () => LoginOutcome.Handled,
+    }))
+    service.registerPrecondition({ alias: 'allow', check: () => true })
+
+    expect(await service.begin({ url: '/dispatcher' })).toBe(LoginOutcome.Handled)
+  })
+
+  test('a registered notifier hears the settled outcome of begin and logout', async () => {
+    const [, service] = bootstrap()
+    service.registerPlugin(stubPlugin({
+      alias: 'blocking', match: () => true,
+      begin: async () => LoginOutcome.Blocked,
+      logout: async () => LoginOutcome.Blocked,
+    }))
+    const seen: LoginOutcome[] = []
+    service.registerNotifier(outcome => { seen.push(outcome) })
+
+    expect(await service.begin({ url: '/dispatcher' })).toBe(LoginOutcome.Blocked)
+    expect(await service.logout({ url: '/dispatcher' })).toBe(LoginOutcome.Blocked)
+    expect(seen).toEqual([LoginOutcome.Blocked, LoginOutcome.Blocked])
+  })
+
+  test('a plugin with no logout still ends the session it was asked to end', async () => {
+    const [context, service] = bootstrap()
+    context.configure()
+    await context.init()
+    service.registerPlugin(stubPlugin({ alias: 'plain', match: () => true }))
+    const auth = context.service<{ token?: string, update: (t?: string) => Promise<void> }>('auth')
+
+    expect(await service.logout({ url: '' })).toBe(LoginOutcome.Passed)
+    expect(auth.token == null || auth.token === '').toBe(true)
+  })
+})
+
+describe('login method resolution', () => {
+  test('methods sort by declared order, ties by id', () => {
+    const context = makeTestContext()
+    const source = {
+      alias: 'test', list: () => [
+        method({ id: 'b', order: 10 }), method({ id: 'a', order: 10 }), method({ id: 'z', order: 1 }),
+      ],
+    }
+
+    const resolved = loginMethodsHelper.resolveLoginMethods(methodCtx(context), undefined, [source])
+
+    expect(resolved.map(item => item.id)).toEqual(['z', 'a', 'b'])
+  })
+
+  test('a restricted method is not offered until the configuration asks for it', () => {
+    const context = makeTestContext()
+    const source = {
+      alias: 'test', list: () => [method({ id: 'ordinary' }), method({ id: 'operator', restricted: true })],
+    }
+
+    expect(loginMethodsHelper.resolveLoginMethods(methodCtx(context), undefined, [source]).map(m => m.id))
+      .toEqual(['ordinary'])
+    expect(loginMethodsHelper.resolveLoginMethods(
+      methodCtx(context), { overrides: { operator: { enabled: true } } }, [source]
+    ).map(m => m.id).sort()).toEqual(['operator', 'ordinary'])
+    expect(loginMethodsHelper.resolveLoginMethods(
+      methodCtx(context), { methods: ['operator'] }, [source]
+    ).map(m => m.id)).toEqual(['operator'])
+  })
+
+  test('an explicit list is both the filter and the order', () => {
+    const context = makeTestContext()
+    const source = {
+      alias: 'test', list: () => [method({ id: 'a' }), method({ id: 'b' }), method({ id: 'c' })],
+    }
+
+    expect(loginMethodsHelper.resolveLoginMethods(methodCtx(context), { methods: ['c', 'a'] }, [source]).map(m => m.id))
+      .toEqual(['c', 'a'])
+  })
+
+  test('a source that throws is skipped rather than taking the screen down', () => {
+    const context = makeTestContext()
+    const broken = { alias: 'broken', list: () => { throw new Error('misconfigured') } }
+    const working = { alias: 'working', list: () => [method({ id: 'ok' })] }
+
+    expect(loginMethodsHelper.resolveLoginMethods(methodCtx(context), undefined, [broken, working]).map(m => m.id))
+      .toEqual(['ok'])
+  })
+
+  test('the primary method is the first emphasised one, else the first', () => {
+    expect(loginMethodsHelper.primaryLoginMethod([
+      method({ id: 'a' }), method({ id: 'b', emphasis: 'primary' }),
+    ])?.id).toBe('b')
+    expect(loginMethodsHelper.primaryLoginMethod([method({ id: 'a' })])?.id).toBe('a')
+    expect(loginMethodsHelper.primaryLoginMethod([])).toBeNull()
+  })
+
+  test('a globally registered source reaches the resolver', () => {
+    const context = makeTestContext()
+    loginMethodsHelper.registerMethodSource({ alias: 'global-test', list: () => [method({ id: 'global' })] })
+
+    expect(loginMethodsHelper.resolveLoginMethods(methodCtx(context)).map(m => m.id)).toContain('global')
+  })
+})
+
+describe('the credit line', () => {
+  const year = new Date().getFullYear()
+
+  test('is a copyright NOTICE — the mark and the year, not a bare name', () => {
+    expect(resolveCredit({ product: 'OwlMeans', organization: 'OwlMeans' }).line)
+      .toBe(`© ${year} OwlMeans`)
+  })
+
+  test('pairs the product with the notice when the product is not the holder', () => {
+    expect(resolveCredit({ product: 'Taskly', organization: 'Acme' }).line)
+      .toBe(`Taskly — © ${year} Acme`)
+  })
+
+  test('falls back to the entity slug when the organization has no name', () => {
+    expect(resolveCredit({ product: 'Taskly', entity: 'acme-7f2' }).line)
+      .toBe(`Taskly — © ${year} acme-7f2`)
+  })
+
+  test('a first year in the past makes the notice a range', () => {
+    expect(resolveCredit({ organization: 'Acme', since: 2019 }).line).toBe(`© 2019–${year} Acme`)
+    // The current year is not a range, and neither is one a skewed clock puts ahead of it.
+    expect(resolveCredit({ organization: 'Acme', since: year }).line).toBe(`© ${year} Acme`)
+    expect(resolveCredit({ organization: 'Acme', since: year + 5 }).line).toBe(`© ${year} Acme`)
+  })
+
+  test('an explicit holder is who the notice names', () => {
+    expect(resolveCredit({ product: 'Taskly', organization: 'Taskly', holder: 'Acme Inc.' }).line)
+      .toBe(`Taskly — © ${year} Acme Inc.`)
+  })
+
+  test('an owner\'s own wording is used verbatim', () => {
+    expect(resolveCredit({ organization: 'Acme', copyright: '© Acme. All rights reserved.' }).line)
+      .toBe('© Acme. All rights reserved.')
+  })
+
+  test('switching the notice off leaves the bare pairing it used to be', () => {
+    expect(resolveCredit({ product: 'Taskly', organization: 'Acme', copyright: false }).line)
+      .toBe('Taskly — Acme')
+    expect(resolveCredit({ product: 'Taskly', copyright: false }).line).toBe('Taskly')
+  })
+
+  test('a literal line replaces the composition entirely', () => {
+    expect(resolveCredit({ product: 'Taskly', organization: 'Acme', line: '© Acme' }).line)
+      .toBe('© Acme')
+  })
+
+  test('nobody to name is nothing to render', () => {
+    expect(resolveCredit().line).toBeNull()
+  })
+
+  test('an EMPTY value is unset, not a value', () => {
+    // Exactly what a platform delivers for branding it does not have: every key present, the
+    // undelivered ones empty. `??` does not fall through an empty string, so the organization
+    // used to win the chain and compose "pisteva — " with nothing after the dash.
+    expect(resolveCredit({}, { name: 'pisteva', organization: '', entity: '' }).line)
+      .toBe(`© ${year} pisteva`)
+    expect(resolveCredit({ line: '', product: '', organization: '' }, { name: 'Taskly' }).line)
+      .toBe(`© ${year} Taskly`)
+    expect(resolveCredit({ copyright: '  ' }, { name: 'Taskly' }).line).toBe(`© ${year} Taskly`)
+    expect(resolveCredit({}, {}, '').line).toBeNull()
+  })
+
+  test('the platform credit is on unless it is switched off', () => {
+    expect(resolveCredit().poweredBy).toBe(true)
+    expect(resolveCredit({ poweredBy: false }).poweredBy).toBe(false)
+  })
+})
+
+describe('the authentication-plugin method source', () => {
+  const plugin = (
+    over: Partial<AuthenticationPlugin> & { type: string }
+  ): AuthenticationPlugin => ({ Implementation: () => () => null, ...over })
+
+  const offered = (context: BasicContext<BasicConfig>): string[] =>
+    pluginMethodSource.list(methodCtx(context)).map(item => item.id)
+
+  test('a plugin that declares no method is not a way to sign in', () => {
+    const context = makeTestContext()
+    authPluginHelper.registerAuthPlugin(plugin({ type: 'step-in-a-flow' }))
+    authPluginHelper.registerAuthPlugin(plugin({ type: 'offerable', method: {} }))
+
+    expect(offered(context)).toContain('offerable')
+    expect(offered(context)).not.toContain('step-in-a-flow')
+  })
+
+  test('a plugin that needs a renderer nobody assigned is left off the screen', () => {
+    const context = makeTestContext()
+    // Exactly the state an app is in when it imported the plugin host but not a panel package:
+    // the plugin is registered, and mounting its screen throws.
+    authPluginHelper.registerAuthPlugin(plugin({ type: 'needs-ui', method: {}, requiresRenderer: true }))
+
+    expect(offered(context)).not.toContain('needs-ui')
+
+    authPluginHelper.registerAuthPlugin(plugin({
+      type: 'needs-ui', method: {}, requiresRenderer: true, Renderer: () => null,
+    }))
+
+    expect(offered(context)).toContain('needs-ui')
+  })
+
+  test('a plugin whose own wiring is absent says so and is left off', () => {
+    const context = makeTestContext()
+    authPluginHelper.registerAuthPlugin(plugin({
+      type: 'needs-wiring', method: { available: ctx => ctx.context.hasService('never-appended') },
+    }))
+
+    expect(offered(context)).not.toContain('needs-wiring')
+  })
+})
+
+describe('a finished sign-in attempt', () => {
+  test('reports every outcome that leaves the user on the screen', () => {
+    // The regression: a method that could not build an authorization URL returned `Passed`, the
+    // screen rendered nothing, and the button read as broken. `Passed` is a valid answer TO A
+    // DISPATCHER, which has a continuation; a screen does not.
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Passed)).toBe('login.error.failed')
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Failed)).toBe('login.error.failed')
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Gesture)).toBe('login.error.blocked')
+    // A `window.open` the browser actually refused reads the same as "needs a fresh gesture" —
+    // both are cured by clicking the browser's own blocked-popup affordance, not by a retry loop.
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Blocked)).toBe('login.error.blocked')
+  })
+
+  test('says nothing when the attempt actually went somewhere', () => {
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Handled)).toBeNull()
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Redirected)).toBeNull()
+    expect(loginResumeHelper.loginAttemptError(LoginOutcome.Orphaned)).toBeNull()
+    expect(loginResumeHelper.loginAttemptError(null)).toBeNull()
+  })
+})
+
+describe('resume outcomes', () => {
+  test('map to exactly one action each', () => {
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Handled)).toBe(ResumeAction.Stop)
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Redirected)).toBe(ResumeAction.Stop)
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Orphaned)).toBe(ResumeAction.Render)
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Failed)).toBe(ResumeAction.Render)
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Gesture)).toBe(ResumeAction.Render)
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Blocked)).toBe(ResumeAction.Render)
+    // The ordinary tab: keep the session and carry on. This is the one that must never change.
+    expect(loginResumeHelper.resumeAction(LoginOutcome.Passed)).toBe(ResumeAction.Navigate)
+  })
+})