@owlmeans/server-payment 0.1.18-rc.2 → 0.1.18-rc.21

package/tests/gate.spec.ts

@@ -1,97 +1,87 @@
 import { describe, expect, test } from 'bun:test'
-import { AppType, makeBasicContext } from '@owlmeans/context'
-import type { BasicConfig } from '@owlmeans/context'
 import type { AbstractRequest, AbstractResponse, GateService } from '@owlmeans/entrypoint'
-import type { Auth } from '@owlmeans/auth'
+import type { Auth, PermissionSet } from '@owlmeans/auth'
 import { AuthForbidden, AuthRole } from '@owlmeans/auth'
-import { CAPABILITY_FEATURE_SCOPE, ENTITLEMENT_GATE } from '@owlmeans/payment'
-import { SubscriptionStatus } from '@owlmeans/payment'
-import { filterRecords } from '@owlmeans/resource'
-import type { Criteria, ResourceRecord } from '@owlmeans/resource'
-import { RES_PAYMENT_SUBSCRIPTION } from '../src/consts.js'
-import { makeEntitlementGate } from '../src/gate.js'
-
-const record = (status: SubscriptionStatus, capabilities?: unknown[]) => ({
-  entityId: 'entity-1',
-  productSku: 'pro',
-  status,
-  capabilities: capabilities ?? [
-    { scope: 'renewable', permissions: { production: 1 } },
-    { scope: CAPABILITY_FEATURE_SCOPE, permissions: { 'branding--whitelabel': true } },
-  ],
-})
-
-/** The gate must fail closed, including when its subscription store is unreadable. */
-const makeGate = async (answer: () => unknown): Promise<GateService> => {
-  const ctx = makeBasicContext<BasicConfig>({
-    ready: false,
-    service: 'server-payment-tests',
-    type: AppType.Backend,
-  })
-  const resource = {
-    alias: RES_PAYMENT_SUBSCRIPTION,
-    list: async (where?: Criteria<ResourceRecord>) => {
-      const items = filterRecords(answer() as ResourceRecord[], where)
-      return { items, total: items.length }
-    },
-    registerContext: () => resource,
-    init: async () => undefined,
-    ready: async () => true,
-  }
-  ctx.registerResource(resource as never)
-  ctx.registerService(makeEntitlementGate())
-  ctx.configure()
-  await ctx.init()
-
-  return ctx.service<GateService>(ENTITLEMENT_GATE)
-}
+import { CapabilityRequired, ENTITLEMENT_GATE, SubscriptionStatus } from '@owlmeans/payment'
+import { entitlementsOf, makeCapabilityGate } from '../src/gate.js'
+import { gateway } from '../src/utils.js'
+import { CAP_BASIC, CAP_PREVIEW, CAP_WHITELABEL, makeFakeContext, past, PRO } from './fake-stripe.js'
+import type { FakeContext } from './fake-stripe.js'
 
 const request = (auth: Partial<Auth> | null = {}): AbstractRequest => ({
   alias: 'test', headers: {}, params: {}, query: {}, body: {}, path: '/',
   ...(auth != null ? {
     auth: {
       type: 'ed25519-basic-token', token: 't', userId: 'u', role: AuthRole.User,
-      scopes: [], entitySlug: 'entity-1', isUser: true, createdAt: new Date(), ...auth,
+      scopes: ['*'], entitySlug: 'entity-1', isUser: true, createdAt: new Date(), ...auth,
     } satisfies Auth,
   } : {}),
 }) as unknown as AbstractRequest
 
 const res = {} as AbstractResponse<unknown>
 
-describe('@owlmeans/server-payment — the entitlement gate', () => {
-  test('passes capabilities from active and trial subscriptions', async () => {
-    for (const status of [SubscriptionStatus.Active, SubscriptionStatus.Trial]) {
-      const gate = await makeGate(() => [record(status)])
-      await gate.assert(request(), res, ['feature:branding--whitelabel'])
+const withPro = async (status: SubscriptionStatus = SubscriptionStatus.Active): Promise<FakeContext> => {
+  const fake = await makeFakeContext()
+  await gateway(fake.ctx).grantInternalPlan(fake.ctx, 'entity-1', PRO, { force: true })
+  fake.stores['payment-subscription'].rows[0].status = status
+  return fake
+}
+
+const gateOf = (fake: FakeContext, alias: string = ENTITLEMENT_GATE): GateService => fake.ctx.service<GateService>(alias)
+
+describe('@owlmeans/server-payment — the capability gate', () => {
+  test('passes a capability of an active, trial or past-due plan; parameters are any-of', async () => {
+    for (const status of [SubscriptionStatus.Active, SubscriptionStatus.Trial, SubscriptionStatus.PastDue]) {
+      const fake = await withPro(status)
+      await gateOf(fake).assert(request(), res, [CAP_WHITELABEL])
+      await gateOf(fake).assert(request(), res, ['feature:nothing--here', CAP_WHITELABEL])
     }
   })
 
-  test('refuses cancelled, missing, and unrelated capabilities', async () => {
-    const canceled = await makeGate(() => [record(SubscriptionStatus.Canceled)])
-    await expect(canceled.assert(request(), res, ['feature:branding--whitelabel']))
-      .rejects.toBeInstanceOf(AuthForbidden)
-    const unrelated = await makeGate(() => [record(SubscriptionStatus.Active)])
-    await expect(unrelated.assert(request(), res, ['feature:domain--custom']))
-      .rejects.toBeInstanceOf(AuthForbidden)
-  })
+  test('refuses a canceled plan, an unrelated capability and a lapsed promo with CapabilityRequired (a 403)', async () => {
+    const canceled = await withPro(SubscriptionStatus.Canceled)
+    const refusal = await gateOf(canceled).assert(request(), res, [CAP_WHITELABEL]).catch(error => error)
+    expect(refusal).toBeInstanceOf(CapabilityRequired)
+    expect(refusal).toBeInstanceOf(AuthForbidden)
+    expect(refusal.params).toEqual([CAP_WHITELABEL])
+    await gateOf(canceled).assert(request(), res, [CAP_BASIC])
 
-  test('treats gate parameters as any-of', async () => {
-    const gate = await makeGate(() => [record(SubscriptionStatus.Active)])
-    await gate.assert(request(), res, ['feature:nothing--here', 'feature:branding--whitelabel'])
+    const unrelated = await withPro()
+    await expect(gateOf(unrelated).assert(request(), res, ['feature:domain--custom'])).rejects.toBeInstanceOf(CapabilityRequired)
+
+    const lapsed = await makeFakeContext({ catalogue: { previewUntil: past(1) } })
+    await expect(gateOf(lapsed).assert(request(), res, [CAP_PREVIEW])).rejects.toBeInstanceOf(CapabilityRequired)
+    expect((await entitlementsOf(lapsed.ctx, 'entity-1')).some(set => set.permissions.preview != null)).toBe(false)
   })
 
-  test('refuses missing authentication or organization before reading storage', async () => {
-    const unread = await makeGate(() => { throw new Error('must not be reached') })
-    await expect(unread.assert(request(null), res, ['feature:branding--whitelabel']))
-      .rejects.toBeInstanceOf(AuthForbidden)
-    const noEntity = await makeGate(() => [])
-    await expect(noEntity.assert(request({ entitySlug: undefined }), res, ['feature:branding--whitelabel']))
-      .rejects.toBeInstanceOf(AuthForbidden)
+  test('refuses a missing authentication or organization before reading storage, and an unreadable store', async () => {
+    const fake = await withPro()
+    fake.stores['payment-subscription'].failing.add('list')
+    const noAuth = await gateOf(fake).assert(request(null), res, [CAP_WHITELABEL]).catch(error => error)
+    expect(noAuth).toBeInstanceOf(AuthForbidden)
+    expect(noAuth).not.toBeInstanceOf(CapabilityRequired)
+    const noEntity = await gateOf(fake).assert(request({ entitySlug: undefined }), res, [CAP_WHITELABEL]).catch(error => error)
+    expect(noEntity).not.toBeInstanceOf(CapabilityRequired)
+    expect(noEntity).toBeInstanceOf(AuthForbidden)
+
+    await expect(gateOf(fake).assert(request(), res, [CAP_WHITELABEL])).rejects.toBeInstanceOf(CapabilityRequired)
   })
 
-  test('refuses when the subscription store is unreadable', async () => {
-    const gate = await makeGate(() => { throw new Error('mongo is down') })
-    await expect(gate.assert(request(), res, ['feature:branding--whitelabel']))
-      .rejects.toBeInstanceOf(AuthForbidden)
+  test('the plan is the authority: a token false denies, a token grant alone never allows, requirePermission is opt-in', async () => {
+    const deny: PermissionSet[] = [{ scope: 'feature', permissions: { whitelabel: false } }]
+    const grant: PermissionSet[] = [{ scope: 'feature', permissions: { whitelabel: true } }]
+
+    const fake = await withPro()
+    await expect(gateOf(fake).assert(request({ permissions: deny }), res, [CAP_WHITELABEL]))
+      .rejects.toBeInstanceOf(CapabilityRequired)
+
+    const free = await makeFakeContext()
+    await expect(gateOf(free).assert(request({ permissions: grant }), res, [CAP_WHITELABEL]))
+      .rejects.toBeInstanceOf(CapabilityRequired)
+
+    fake.ctx.registerService(makeCapabilityGate('strict-gate', { requirePermission: true }))
+    await expect(gateOf(fake, 'strict-gate').assert(request(), res, [CAP_WHITELABEL]))
+      .rejects.toBeInstanceOf(CapabilityRequired)
+    await gateOf(fake, 'strict-gate').assert(request({ permissions: grant }), res, [CAP_WHITELABEL])
   })
 })

package/tests/limit-gate.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test'
+import type { AbstractRequest, AbstractResponse, GateService } from '@owlmeans/entrypoint'
+import type { Auth } from '@owlmeans/auth'
+import { AuthForbidden, AuthRole } from '@owlmeans/auth'
+import {
+  formatLimitParam, LIMIT_GATE, LimitExhausted, LimitWindow, windowBoundsOf,
+} from '@owlmeans/payment'
+import { entitlements, gateway } from '../src/utils.js'
+import { makeFakeContext, PRO } from './fake-stripe.js'
+import type { FakeContext } from './fake-stripe.js'
+
+const request = (auth: Partial<Auth> | null = {}): AbstractRequest => ({
+  alias: 'test', headers: {}, params: {}, query: {}, body: {}, path: '/',
+  ...(auth != null ? {
+    auth: {
+      type: 'ed25519-basic-token', token: 't', userId: 'u', role: AuthRole.User,
+      scopes: ['*'], entitySlug: 'entity-1', isUser: true, createdAt: new Date(), ...auth,
+    } satisfies Auth,
+  } : {}),
+}) as unknown as AbstractRequest
+
+const res = {} as AbstractResponse<unknown>
+const gateOf = (fake: FakeContext): GateService => fake.ctx.service<GateService>(LIMIT_GATE)
+
+describe('@owlmeans/server-payment — the limit gate', () => {
+  test('passes with room and consumes nothing', async () => {
+    const fake = await makeFakeContext()
+    await gateOf(fake).assert(request(), res, [formatLimitParam('exports')])
+    await gateOf(fake).assert(request(), res, [formatLimitParam('exports')])
+
+    expect(fake.stores['payment-usage'].rows).toHaveLength(0)
+    expect(fake.stores['payment-usage-counter'].rows).toHaveLength(0)
+  })
+
+  test('refuses at the ceiling with the limit, the usage and the reset date', async () => {
+    const fake = await makeFakeContext()
+    await entitlements(fake.ctx).consume({ entityId: 'entity-1', limitKey: 'exports', eventKey: 'export:1' })
+
+    const refusal = await gateOf(fake).assert(request(), res, [formatLimitParam('exports')]).catch(error => error)
+    expect(refusal).toBeInstanceOf(LimitExhausted)
+    expect(refusal).toBeInstanceOf(AuthForbidden)
+    expect(refusal).toEqual(expect.objectContaining({
+      limitKey: 'exports', used: 1, limit: 1, resetsAt: windowBoundsOf(LimitWindow.Month).resetsAt,
+    }))
+    await expect(gateOf(fake).assert(request(), res, [formatLimitParam('reports', 2)])).rejects.toBeInstanceOf(LimitExhausted)
+  })
+
+  test('skips malformed and undeclared parameters, ORs the rest, and refuses when none is left', async () => {
+    const fake = await makeFakeContext()
+    await gateway(fake.ctx).grantInternalPlan(fake.ctx, 'entity-1', PRO, { force: true })
+    await gateOf(fake).assert(request(), res, ['feature:exports', 'limit:', formatLimitParam('nope'), formatLimitParam('seats')])
+
+    const seats = await gateOf(fake).assert(request(), res, [formatLimitParam('seats', 3), formatLimitParam('exports')])
+    expect(seats).toBeUndefined()
+
+    const malformed = await gateOf(fake).assert(request(), res, ['garbage', 'feature:x']).catch(error => error)
+    expect(malformed).toBeInstanceOf(LimitExhausted)
+    expect(malformed.limitKey).toBe('garbage')
+  })
+
+  test('refuses when authentication is missing or the store cannot be read', async () => {
+    const fake = await makeFakeContext()
+    await expect(gateOf(fake).assert(request(null), res, [formatLimitParam('exports')])).rejects.toBeInstanceOf(AuthForbidden)
+
+    fake.stores['payment-usage-counter'].failing.add('load')
+    await expect(gateOf(fake).assert(request(), res, [formatLimitParam('exports')])).rejects.toBeInstanceOf(LimitExhausted)
+  })
+})

package/tests/portal.spec.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from 'bun:test'
+import { PortalFlow, PortalUnavailable, ProductType, PlanDuration, SubscriptionStatus, TaxBehavior } from '@owlmeans/payment'
+import { declarePaymentPlan, declarePaymentPricing, declarePaymentProduct } from '../src/config.js'
+import { createPortalLink, ensurePortalConfiguration } from '../src/plugins/portal.js'
+import { fingerprints, paygateCustomers, subscriptions } from '../src/utils.js'
+import { makeFakeContext, PLANS_PRODUCT, PRO, SERVICE, TEAM } from './fake-stripe.js'
+import type { FakeContextOptions } from './fake-stripe.js'
+
+const RETURN = 'https://app.example.com/billing'
+const hookOf = (host: string): string => `https://${host}/payment-gate/webhook/stripe`
+const tagOf = (host: string) => ({ owlmeans: 'payment', service: SERVICE, deployment: hookOf(host) })
+const prices = [
+  { id: 'price_pro', product: PLANS_PRODUCT, lookup_key: PRO, active: true, recurring: { interval: 'month' } },
+  { id: 'price_team', product: PLANS_PRODUCT, lookup_key: TEAM, active: true, recurring: { interval: 'month' } },
+  { id: 'price_old', product: PLANS_PRODUCT, lookup_key: null, active: false, recurring: { interval: 'month' } },
+  { id: 'price_once', product: PLANS_PRODUCT, lookup_key: 'once', active: true, recurring: null },
+]
+
+const withPortal = async (opts: FakeContextOptions = {}) => await makeFakeContext({
+  portal: { returnUrl: RETURN, headline: 'Plans', privacyPolicyUrl: 'https://example.com/privacy' },
+  ...opts, stripe: { prices: structuredClone(prices), ...opts.stripe },
+})
+
+describe('@owlmeans/server-payment — portal configuration', () => {
+  test('offers switching between active recurring prices and cancellation at period end; unchanged means no call', async () => {
+    const fake = await withPortal()
+    const id = await ensurePortalConfiguration(fake.ctx, fake.stripe)
+    const [configuration] = fake.state.portalConfigurations
+
+    expect(configuration.id).toBe(id)
+    expect(configuration.features.subscription_update).toEqual({
+      enabled: true, default_allowed_updates: ['price'], proration_behavior: 'create_prorations',
+      products: [{ product: PLANS_PRODUCT, prices: ['price_pro', 'price_team'] }],
+    })
+    expect(configuration.features.subscription_cancel).toEqual({ enabled: true, mode: 'at_period_end', proration_behavior: 'none' })
+    expect(configuration.features.customer_update).toEqual({ enabled: true, allowed_updates: ['email', 'address', 'tax_id'] })
+    expect(configuration).toEqual(expect.objectContaining({
+      default_return_url: RETURN, metadata: tagOf('api.example.com'),
+      business_profile: { headline: 'Plans', privacy_policy_url: 'https://example.com/privacy' },
+    }))
+
+    fake.state.calls.length = 0
+    expect(await ensurePortalConfiguration(fake.ctx, fake.stripe)).toBe(id)
+    expect(fake.state.calls).toEqual([])
+  })
+
+  test('re-adopts its own untracked configuration, and never an untagged one or one tagged for another deployment', async () => {
+    const fake = await withPortal({
+      stripe: {
+        prices: structuredClone(prices),
+        portalConfigurations: [
+          { id: 'bpc_service_only', active: true, metadata: { owlmeans: 'payment', service: SERVICE } },
+          { id: 'bpc_other', active: true, metadata: tagOf('other.example.com') },
+        ],
+      },
+    })
+    const id = await ensurePortalConfiguration(fake.ctx, fake.stripe)
+    expect(id).not.toBe('bpc_service_only')
+    expect(id).not.toBe('bpc_other')
+
+    await fingerprints(fake.ctx).clear()
+    fake.state.calls.length = 0
+    expect(await ensurePortalConfiguration(fake.ctx, fake.stripe, { force: true })).toBe(id)
+    expect(fake.state.calls).toEqual(['prices.list', 'billingPortal.configurations.list', 'billingPortal.configurations.update'])
+    expect(fake.stores['payment-fingerprint'].rows).toEqual([
+      expect.objectContaining({ sku: `portal:${SERVICE}`, externalId: id }),
+    ])
+    expect(fake.state.portalConfigurations.map(({ id, metadata, features }) => ({ id, metadata, features: features != null })))
+      .toEqual([
+        { id: 'bpc_service_only', metadata: { owlmeans: 'payment', service: SERVICE }, features: false },
+        { id: 'bpc_other', metadata: tagOf('other.example.com'), features: false },
+        { id, metadata: tagOf('api.example.com'), features: true },
+      ])
+  })
+
+  test('a declared tax behavior is hashed: changing it re-hashes and updates the configuration', async () => {
+    const fake = await withPortal({
+      pricing: { tax: { automatic: true, collectTaxId: true, estimate: false, behavior: TaxBehavior.Exclusive }, currency: { estimate: false } },
+    })
+    const id = await ensurePortalConfiguration(fake.ctx, fake.stripe)
+    fake.state.calls.length = 0
+    expect(await ensurePortalConfiguration(fake.ctx, fake.stripe)).toBe(id)
+    expect(fake.state.calls).toEqual([])
+
+    declarePaymentPricing(fake.ctx.cfg as never, {
+      tax: { automatic: true, collectTaxId: true, estimate: false, behavior: TaxBehavior.Inclusive },
+      currency: { estimate: false },
+    })
+    expect(await ensurePortalConfiguration(fake.ctx, fake.stripe)).toBe(id)
+    expect(fake.state.calls).toContain('billingPortal.configurations.update')
+  })
+
+  test('two deployments on one Stripe account keep separate configurations, even when both rows name one', async () => {
+    const shared = { owlmeans: 'payment', service: SERVICE }
+    const stage = await withPortal({
+      host: 'stage.example.com',
+      stripe: { prices: structuredClone(prices), portalConfigurations: [{ id: 'bpc_shared', active: true, metadata: shared }] },
+    })
+    const staging = await withPortal({ host: 'staging.example.com' })
+    for (const deployment of [stage, staging]) {
+      await fingerprints(deployment.ctx).create({ sku: `portal:${SERVICE}`, hash: 'legacy', externalId: 'bpc_shared', updatedAt: new Date() })
+    }
+
+    expect(await ensurePortalConfiguration(stage.ctx, stage.stripe)).toBe('bpc_shared')
+    const stagingId = await ensurePortalConfiguration(staging.ctx, stage.stripe)
+    expect(stagingId).not.toBe('bpc_shared')
+    expect(stage.state.portalConfigurations.map(({ id, metadata }) => ({ id, metadata }))).toEqual([
+      { id: 'bpc_shared', metadata: tagOf('stage.example.com') },
+      { id: stagingId, metadata: tagOf('staging.example.com') },
+    ])
+
+    for (const deployment of [stage, staging]) {
+      await fingerprints(deployment.ctx).clear()
+    }
+    expect(await ensurePortalConfiguration(staging.ctx, stage.stripe, { force: true })).toBe(stagingId)
+    expect(await ensurePortalConfiguration(stage.ctx, stage.stripe, { force: true })).toBe('bpc_shared')
+    expect(stage.state.portalConfigurations).toHaveLength(2)
+
+    const local = await withPortal({ host: 'localhost' })
+    const localId = await ensurePortalConfiguration(local.ctx, stage.stripe)
+    expect(stage.state.portalConfigurations.find(configuration => configuration.id === localId)?.metadata)
+      .toEqual(tagOf('localhost'))
+    expect(stage.state.portalConfigurations).toHaveLength(3)
+  })
+
+  test('disables both subscription features when nothing recurring is sold', async () => {
+    const fake = await makeFakeContext({
+      declare: cfg => {
+        declarePaymentProduct(cfg, { sku: 'kit', type: ProductType.Simple, services: [SERVICE], name: 'Kit' })
+        declarePaymentPlan(cfg, { productSku: 'kit', sku: 'kit-once', duration: PlanDuration.Lifetime, price: 5 })
+      },
+    })
+    await ensurePortalConfiguration(fake.ctx, fake.stripe)
+    expect(fake.state.portalConfigurations[0].features.subscription_update).toEqual({ enabled: false })
+    expect(fake.state.portalConfigurations[0].features.subscription_cancel).toEqual({ enabled: false })
+  })
+})
+
+describe('@owlmeans/server-payment — portal links', () => {
+  const subscribed = async () => {
+    const fake = await withPortal()
+    await paygateCustomers(fake.ctx).create({ paygate: 'stripe', externalId: 'cus_1', entityId: 'entity-1' })
+    await subscriptions(fake.ctx).create({
+      entityId: 'entity-1', planSku: PRO, productSku: PLANS_PRODUCT, service: SERVICE, paygate: 'stripe',
+      externalId: 'sub_1', itemId: 'si_1', status: SubscriptionStatus.Active, rank: 10, createdAt: new Date(),
+    })
+    return fake
+  }
+
+  test('needs a customer; Manage opens the portal home on the managed configuration', async () => {
+    const empty = await withPortal()
+    await expect(createPortalLink(empty.ctx, empty.stripe, 'entity-1', { flow: PortalFlow.Manage, returnUrl: RETURN }))
+      .rejects.toBeInstanceOf(PortalUnavailable)
+
+    const fake = await subscribed()
+    const url = await createPortalLink(fake.ctx, fake.stripe, 'entity-1', { flow: PortalFlow.Manage, returnUrl: RETURN })
+    expect(url).toStartWith('https://billing.example.test/')
+    expect(fake.state.portalSessions[0]).toEqual({
+      customer: 'cus_1', return_url: RETURN, configuration: fake.state.portalConfigurations[0].id,
+    })
+  })
+
+  test('PaymentMethod, Cancel and Update deep-link with a redirect back', async () => {
+    const fake = await subscribed()
+    const after = { type: 'redirect', redirect: { return_url: RETURN } }
+    for (const flow of [PortalFlow.PaymentMethod, PortalFlow.Cancel, PortalFlow.Update]) {
+      await createPortalLink(fake.ctx, fake.stripe, 'entity-1', { flow, returnUrl: RETURN })
+    }
+    expect(fake.state.portalSessions.map(session => session.flow_data)).toEqual([
+      { type: 'payment_method_update', after_completion: after },
+      { type: 'subscription_cancel', subscription_cancel: { subscription: 'sub_1' }, after_completion: after },
+      { type: 'subscription_update', subscription_update: { subscription: 'sub_1' }, after_completion: after },
+    ])
+  })
+
+  test('Change confirms the stored item switching to the target plan price, as one item', async () => {
+    const fake = await subscribed()
+    await createPortalLink(fake.ctx, fake.stripe, 'entity-1', { flow: PortalFlow.Change, planSku: TEAM, returnUrl: RETURN })
+    expect(fake.state.portalSessions[0].flow_data).toEqual({
+      type: 'subscription_update_confirm',
+      subscription_update_confirm: { subscription: 'sub_1', items: [{ id: 'si_1', price: 'price_team', quantity: 1 }] },
+      after_completion: { type: 'redirect', redirect: { return_url: RETURN } },
+    })
+    await expect(createPortalLink(fake.ctx, fake.stripe, 'entity-1', { flow: PortalFlow.Change, returnUrl: RETURN }))
+      .rejects.toBeInstanceOf(PortalUnavailable)
+  })
+
+  test('a subscription flow without an entitling paygate subscription is unavailable', async () => {
+    const fake = await withPortal()
+    await paygateCustomers(fake.ctx).create({ paygate: 'stripe', externalId: 'cus_1', entityId: 'entity-1' })
+    await subscriptions(fake.ctx).create({
+      entityId: 'entity-1', planSku: PRO, productSku: PLANS_PRODUCT, service: SERVICE, paygate: 'stripe',
+      externalId: 'sub_1', itemId: 'si_1', status: SubscriptionStatus.Canceled, rank: 10, createdAt: new Date(),
+    })
+    const refusal = await createPortalLink(fake.ctx, fake.stripe, 'entity-1', { flow: PortalFlow.Cancel, returnUrl: RETURN })
+      .catch(error => error)
+    expect(refusal).toBeInstanceOf(PortalUnavailable)
+    expect(refusal.message).toContain('subscription')
+  })
+})

package/tests/protocol.spec.ts

@@ -1,20 +1,37 @@
 import { describe, expect, test } from 'bun:test'
+import { protocols } from '@owlmeans/entrypoint'
 import type { ParamsOf, ResponseOf } from '@owlmeans/entrypoint'
-import { paymentGate, paymentGateProtocols } from '../src/index.js'
+import { GUARD_ED25519 } from '@owlmeans/server-app'
+import * as payment from '../src/index.js'
+import { paymentGate, paymentGateEntrypoints, WEBHOOK_EVENTS } from '../src/index.js'
 
 describe('server payment protocols', () => {
-  test('bind webhook params and resync response to their declarations', () => {
+  test('bind webhook params and the resync responses to their declarations', () => {
     const params: ParamsOf<typeof paymentGate.webhook> = { paygate: 'stripe' }
     const response: ResponseOf<typeof paymentGate.resync> = { ok: true }
+    const resynced: ResponseOf<typeof paymentGate.resyncSubscriptions> = { scanned: 3, updated: 1 }
 
     expect(params.paygate).toBe('stripe')
     expect(response.ok).toBe(true)
+    expect(resynced.updated).toBe(1)
     expect(paymentGate.webhook.route.route.parent).toBe(paymentGate.base.alias)
+    expect(paymentGate.resyncSubscriptions.route.route.parent).toBe(paymentGate.base.alias)
   })
 
-  test('exports a flattened list of immutable protocol objects', () => {
-    expect(paymentGateProtocols).toContain(paymentGate.webhook)
-    expect(paymentGateProtocols.every(item => item.kind === 'entrypoint-protocol')).toBe(true)
-    expect(Object.isFrozen(paymentGate.resync)).toBe(true)
+  test('exports an immutable protocol tree without a flattened compatibility list', () => {
+    expect(protocols(paymentGate)).toContain(paymentGate.webhook)
+    expect(protocols(paymentGate)).toContain(paymentGate.resyncSubscriptions)
+    expect(protocols(paymentGate).every(item => item.kind === 'entrypoint-protocol')).toBe(true)
+    expect(payment).not.toHaveProperty('paymentGateProtocols')
+    expect(Object.isFrozen(paymentGate.resyncSubscriptions)).toBe(true)
+    expect(paymentGateEntrypoints).toHaveLength(4)
+  })
+
+  test('guards both resync routes with the service signature and leaves the webhook public', () => {
+    expect(JSON.stringify(paymentGate.resyncSubscriptions)).toContain(GUARD_ED25519)
+    expect(JSON.stringify(paymentGate.resync)).toContain(GUARD_ED25519)
+    expect(JSON.stringify(paymentGate.webhook)).not.toContain(GUARD_ED25519)
+    expect(Object.isFrozen(WEBHOOK_EVENTS)).toBe(true)
+    expect(new Set(WEBHOOK_EVENTS).size).toBe(WEBHOOK_EVENTS.length)
   })
 })

package/tests/sync.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from 'bun:test'
+import { TaxBehavior } from '@owlmeans/payment'
+import type { PricingDef } from '../src/types.js'
+import { syncStripeProducts } from '../src/sync.js'
+import { makeFakeContext, PLANS_PRODUCT, PRO } from './fake-stripe.js'
+import type { FakeContextOptions } from './fake-stripe.js'
+
+const exclusive: PricingDef = {
+  tax: { automatic: true, collectTaxId: true, estimate: false, behavior: TaxBehavior.Exclusive },
+  currency: { estimate: false },
+}
+
+const inclusiveAccountDefault = {
+  defaults: { tax_behavior: 'inclusive' as const, tax_code: null }, head_office: null,
+  status: 'active' as const, status_details: {},
+}
+
+/** A price already in place, matching PRO's lookup key, amount, currency and interval. */
+const existingProPrice = (taxBehavior: string, id = 'price_pro_existing') => ({
+  id, product: PLANS_PRODUCT, lookup_key: PRO, active: true, unit_amount: 2_000, currency: 'usd',
+  recurring: { interval: 'month' }, tax_behavior: taxBehavior,
+})
+
+const withProProduct = async (opts: FakeContextOptions = {}) => await makeFakeContext(opts)
+const proPrice = (fake: Awaited<ReturnType<typeof withProProduct>>) =>
+  fake.state.prices.find(item => item.lookup_key === PRO && item.active)
+
+describe('@owlmeans/server-payment — price tax_behavior sync', () => {
+  test('an undeclared policy creates a price with no forced tax_behavior (Stripe defaults it to unspecified)', async () => {
+    const fake = await withProProduct()
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(proPrice(fake)?.tax_behavior).toBe('unspecified')
+  })
+
+  test('re-syncing an unchanged, undeclared catalogue makes no paygate call', async () => {
+    const fake = await withProProduct()
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    fake.state.calls.length = 0
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(fake.state.calls).toEqual([])
+  })
+
+  test('a declared behavior sets tax_behavior on a freshly created price', async () => {
+    const fake = await withProProduct({ pricing: exclusive })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(proPrice(fake)?.tax_behavior).toBe('exclusive')
+  })
+
+  test("a declared behavior updates a pre-existing 'unspecified' price IN PLACE — the id is kept", async () => {
+    const fake = await withProProduct({ pricing: exclusive, stripe: { prices: [existingProPrice('unspecified')] } })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(fake.state.calls).toContain('prices.update')
+    // PRO's own price keeps its id (an update, not a replacement) — TEAM's plan has no price
+    // fixture, so it legitimately goes through `prices.create` alongside it.
+    expect(proPrice(fake)).toEqual(expect.objectContaining({ id: 'price_pro_existing', tax_behavior: 'exclusive' }))
+  })
+
+  test("an inclusive account default skips the in-place update and leaves the price 'unspecified'", async () => {
+    const fake = await withProProduct({
+      pricing: exclusive, stripe: { prices: [existingProPrice('unspecified')], taxSettings: inclusiveAccountDefault },
+    })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(fake.state.calls).toContain('tax.settings.retrieve')
+    expect(fake.state.calls).not.toContain('prices.update')
+    expect(proPrice(fake)?.tax_behavior).toBe('unspecified')
+  })
+
+  test("'stripe.migrateUnspecifiedPrices' overrides the account-default guard, without even checking it", async () => {
+    const fake = await withProProduct({
+      pricing: { ...exclusive, stripe: { migrateUnspecifiedPrices: true } },
+      stripe: { prices: [existingProPrice('unspecified')], taxSettings: inclusiveAccountDefault },
+    })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(fake.state.calls).not.toContain('tax.settings.retrieve')
+    expect(proPrice(fake)?.tax_behavior).toBe('exclusive')
+  })
+
+  test('a price already carrying the OPPOSITE behavior is deactivated and replaced, never mutated', async () => {
+    const fake = await withProProduct({ pricing: exclusive, stripe: { prices: [existingProPrice('inclusive')] } })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    const old = fake.state.prices.find(item => item.id === 'price_pro_existing')
+    const fresh = proPrice(fake)
+    expect(old?.active).toBe(false)
+    expect(old?.tax_behavior).toBe('inclusive')
+    expect(fresh?.id).not.toBe('price_pro_existing')
+    expect(fresh).toEqual(expect.objectContaining({ tax_behavior: 'exclusive', lookup_key: PRO }))
+  })
+
+  test('recurring USD catalogue prices are synchronized as EUR settlement prices', async () => {
+    const fake = await withProProduct({
+      pricing: { ...exclusive, stripe: { settlementCurrency: 'eur' } },
+      stripe: { fxRates: { usd: { exchangeRate: 0.853568, referenceRate: 0.8726 } } },
+    })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(proPrice(fake)).toEqual(expect.objectContaining({ currency: 'eur', unit_amount: 1_746 }))
+    expect(fake.state.rawRequests).toContainEqual(expect.objectContaining({
+      params: { to_currency: 'eur', 'from_currencies[]': 'usd', lock_duration: 'none' },
+    }))
+  })
+
+  test('a changed reference rate replaces a recurring settlement price on the next sync', async () => {
+    const fake = await withProProduct({
+      pricing: { ...exclusive, stripe: { settlementCurrency: 'eur' } },
+      stripe: { fxRates: { usd: { exchangeRate: 0.853568, referenceRate: 0.8726 } } },
+    })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    const first = proPrice(fake)
+    fake.state.fxRates.usd = { exchangeRate: 0.88, referenceRate: 0.9 }
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(first?.active).toBe(false)
+    expect(proPrice(fake)).toEqual(expect.objectContaining({ currency: 'eur', unit_amount: 1_800 }))
+    expect(proPrice(fake)?.id).not.toBe(first?.id)
+  })
+})