@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/components/identity.federation/source/delete.ts

@@ -0,0 +1,19 @@
+import type { Context } from './types/index.js'
+
+export async function effect(
+  { authority, identity, credential }: Input,
+  context: Context
+): Promise<void | null> {
+  const object = await context.local.observe({ query: { id: credential } })
+
+  if (object === null || object.authority !== authority || object.identity !== identity)
+    return null
+
+  return await context.local.terminate({ query: { id: credential } })
+}
+
+interface Input {
+  authority: string
+  identity: string
+  credential: string
+}

package/components/identity.federation/source/incept.ts

@@ -1,27 +1,24 @@
-import { assertionsAsValues } from './lib/assertions-as-values.js'
-import { validateIdToken } from './lib/jwt'
-import type { Request } from '@toa.io/core'
-import type { Context, Entity } from './types'
+import { effect as create } from './create.js'
+import { principal } from './lib/index.js'
+import type { Context, Scheme } from './types/index.js'
 
-async function incept (input: Input, context: Context): Promise<Output> {
-  const { iss, sub } = await validateIdToken(input.credentials, context.configuration.trust)
+export async function effect(input: Input, context: Context): Promise<Output | Error> {
+  const credential = await create(input, context)
 
-  const request: Request = { input: { authority: input.authority, iss, sub } satisfies Omit<Entity, 'id'> }
+  if (credential instanceof Error) return credential
 
-  if (input.id !== undefined)
-    request.query = { id: input.id }
+  await principal(credential, context)
 
-  return await context.local.transit(request)
+  return { id: credential.identity }
 }
 
-interface Input {
+export interface Input {
   authority: string
+  scheme: Scheme
   credentials: string
-  id?: string
+  id: string
 }
 
-interface Output {
+export interface Output {
   id: string
 }
-
-export const effect = assertionsAsValues(incept)

package/components/identity.federation/source/lib/Configuration.ts

@@ -0,0 +1,39 @@
+export interface Configuration extends Record<string, unknown> {
+  issuer: string
+  authorization_endpoint: string
+  token_endpoint: string
+  userinfo_endpoint: string
+  jwks_uri: string
+  registration_endpoint?: string
+  scopes_supported?: string[]
+  response_types_supported: string[]
+  response_modes_supported?: string[]
+  grant_types_supported?: string[]
+  acr_values_supported?: string[]
+  subject_types_supported: string[]
+  id_token_signing_alg_values_supported: string[]
+  id_token_encryption_alg_values_supported?: string[]
+  id_token_encryption_enc_values_supported?: string[]
+  userinfo_signing_alg_values_supported?: string[]
+  userinfo_encryption_alg_values_supported?: string[]
+  userinfo_encryption_enc_values_supported?: string[]
+  request_object_signing_alg_values_supported?: string[]
+  request_object_encryption_alg_values_supported?: string[]
+  request_object_encryption_enc_values_supported?: string[]
+  token_endpoint_auth_methods_supported?: string[]
+  token_endpoint_auth_signing_alg_values_supported?: string[]
+  display_values_supported?: string[]
+  claim_types_supported?: string[]
+  claims_supported?: string[]
+  service_documentation?: string
+  claims_locales_supported?: string[]
+  ui_locales_supported?: string[]
+  claims_parameter_supported?: boolean
+  request_parameter_supported?: boolean
+  request_uri_parameter_supported?: boolean
+  require_request_uri_registration?: boolean
+  op_policy_uri?: string
+  op_tos_uri?: string
+  check_session_iframe?: string
+  end_session_endpoint?: string
+}

package/components/identity.federation/source/lib/Ctx.ts

@@ -0,0 +1,9 @@
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type { Trust } from '../types/index.js'
+import type { Fetch } from '../types/context.js'
+
+export interface Ctx {
+  trust: Trust[]
+  logs: Logs
+  fetch: Fetch
+}

package/components/identity.federation/source/lib/Payload.ts

@@ -0,0 +1,6 @@
+import type * as jose from 'jose'
+
+export interface Payload extends jose.JWTPayload {
+  iss: string
+  sub: string
+}

package/components/identity.federation/source/lib/decode.ts

@@ -0,0 +1,44 @@
+import { load } from './jose.js'
+import { createRemoteJWKSet } from './discovery.js'
+import { ERR_TRUST, ERR_ISS, ERR_SUB, ERR_TOKEN } from './errors.js'
+import type { JWTPayload } from 'jose'
+import type { Ctx } from './Ctx.js'
+import type { Payload } from './Payload.js'
+
+export async function decode(token: string, ctx: Ctx): Promise<Payload | Error> {
+  const jose = await load()
+
+  let claims: JWTPayload
+
+  // jose throws on anything it cannot read, and credentials are the client's to malform
+  try {
+    claims = jose.decodeJwt(token)
+  } catch {
+    return ERR_TOKEN
+  }
+
+  const { iss, sub } = claims
+
+  if (typeof iss !== 'string') return ERR_ISS
+
+  if (typeof sub !== 'string') return ERR_SUB
+
+  const trusted = ctx.trust.find((trust) => trust.iss === iss)
+
+  if (trusted === undefined) return ERR_TRUST
+
+  // the issuer is a configured one by now, so reaching its keys is the deployment's to answer for
+  const jwks = await createRemoteJWKSet(iss, ctx.fetch)
+
+  try {
+    const { payload } = await jose.jwtVerify(token, jwks, {
+      issuer: iss,
+      audience: trusted.aud,
+      requiredClaims: ['exp']
+    })
+
+    return payload as Payload
+  } catch {
+    return ERR_TOKEN
+  }
+}

package/components/identity.federation/source/lib/discovery.test.ts

@@ -0,0 +1,60 @@
+import { it, mock } from 'node:test'
+import type { Mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
+
+import { createRemoteJWKSet, discover } from './discovery.js'
+import { load } from './jose.js'
+import type { Fetch } from '../types/context.js'
+
+it('discovers an issuer using the component fetch', async () => {
+  const iss = `https://${Math.random().toString(36).slice(2)}.example.com`
+  const configuration = { issuer: iss, jwks_uri: `${iss}/jwks` }
+
+  const fetch = mock.fn(async (_input: string | URL | Request) =>
+    Response.json(configuration)
+  ) as Mock<Fetch>
+
+  await assert.partialDeepStrictEqual(await discover(iss, fetch), configuration)
+  assert.ok(
+    fetch.mock.calls.some(
+      (call: any) =>
+        call.arguments.length === 1 &&
+        isDeepStrictEqual(call.arguments[0], `${iss}/.well-known/openid-configuration`)
+    )
+  )
+})
+
+it('loads and caches remote keys using the component fetch', async () => {
+  const jose = await load()
+  const iss = `https://${Math.random().toString(36).slice(2)}.example.com`
+  const jwksUri = `${iss}/jwks`
+  const { privateKey, publicKey } = await jose.generateKeyPair('ES256')
+  const jwk = await jose.exportJWK(publicKey)
+
+  const fetch = mock.fn(async (input: string | URL | Request) => {
+    const url = input instanceof Request ? input.url : input.toString()
+
+    if (url.endsWith('/.well-known/openid-configuration'))
+      return Response.json({ issuer: iss, jwks_uri: jwksUri })
+
+    return Response.json({ keys: [{ ...jwk, alg: 'ES256', kid: 'key0', use: 'sig' }] })
+  }) as Mock<Fetch>
+
+  const token = await new jose.SignJWT({ sub: 'subject' })
+    .setProtectedHeader({ alg: 'ES256', kid: 'key0' })
+    .setIssuer(iss)
+    .sign(privateKey)
+
+  const first = await createRemoteJWKSet(iss, fetch)
+  const second = await createRemoteJWKSet(iss, fetch)
+
+  assert.strictEqual(second, first)
+  await assert.partialDeepStrictEqual(
+    await jose.jwtVerify(token, first, { issuer: iss }),
+    {
+      payload: { sub: 'subject' }
+    }
+  )
+  assert.strictEqual(fetch.mock.callCount(), 2)
+})

package/components/identity.federation/source/lib/discovery.ts

@@ -0,0 +1,50 @@
+import { load } from './jose.js'
+import type * as jose from 'jose'
+import type { Configuration } from './Configuration.js'
+import type { Fetch } from '../types/context.js'
+
+const cache = new Map<string, Configuration>()
+const resolvers = new WeakMap<Fetch, Map<string, Promise<jose.RemoteJWKSet>>>()
+
+export async function discover(iss: string, fetch: Fetch): Promise<Configuration> {
+  if (!cache.has(iss)) {
+    const configuration = await fetchConfiguration(iss, fetch)
+
+    cache.set(iss, configuration)
+  }
+
+  return cache.get(iss)!
+}
+
+async function fetchConfiguration(iss: string, fetch: Fetch): Promise<Configuration> {
+  const response = await fetch(`${iss}/.well-known/openid-configuration`)
+
+  if (!response.ok) throw new Error('Failed to fetch OIDC configuration')
+
+  return (await response.json()) as Configuration
+}
+
+export async function createRemoteJWKSet(
+  iss: string,
+  fetch: Fetch
+): Promise<jose.RemoteJWKSet> {
+  let entries = resolvers.get(fetch)
+
+  if (entries === undefined) {
+    entries = new Map()
+    resolvers.set(fetch, entries)
+  }
+
+  if (!entries.has(iss)) entries.set(iss, create(iss, fetch))
+
+  return await entries.get(iss)!
+}
+
+async function create(iss: string, fetch: Fetch): Promise<jose.RemoteJWKSet> {
+  const jose = await load()
+  const configuration = await discover(iss, fetch)
+
+  return jose.createRemoteJWKSet(new URL(configuration.jwks_uri), {
+    [jose.customFetch]: fetch
+  })
+}

package/components/identity.federation/source/lib/errors.ts

@@ -0,0 +1,54 @@
+export const ERR_TOKEN = new (class TokenError extends Error {
+  public readonly code = 'TOKEN'
+  public override readonly message = 'Token is malformed or does not verify'
+})()
+
+export const ERR_TRUST = new (class TrustError extends Error {
+  public readonly code = 'TRUST'
+  public override readonly message = 'Issuer not trusted'
+})()
+
+export const ERR_RESPONSE = new (class ResponseError extends Error {
+  public readonly code = 'RESPONSE'
+  public override readonly message = 'Request to IDP failed'
+})()
+
+export const ERR_CONFIG = new (class ConfigError extends Error {
+  public readonly code = 'CONFIG'
+  public override readonly message = 'Invalid OpenID configuration'
+})()
+
+export const ERR_NO_TOKEN = new (class NoTokenError extends Error {
+  public readonly code = 'NO_TOKEN'
+  public override readonly message = 'No ID token received'
+})()
+
+export const ERR_ISS = new (class IssError extends Error {
+  public readonly code = 'ISS'
+  public override readonly message = 'Invalid issuer claim'
+})()
+
+export const ERR_SUB = new (class SubError extends Error {
+  public readonly code = 'SUB'
+  public override readonly message = 'Invalid subject claim'
+})()
+
+export const ERR_EXP = new (class ExpError extends Error {
+  public readonly code = 'EXP'
+  public override readonly message = 'Token does not have an expiration time'
+})()
+
+export const ERR_REPLAY = new (class ReplayError extends Error {
+  public readonly code = 'REPLAY'
+  public override readonly message = 'Token has already been used'
+})()
+
+export const ERR_CODE_NOT_ENABLED = new (class CodeNotEnabledError extends Error {
+  public readonly code = 'CODE_NOT_ENABLED'
+  public override readonly message = 'Authorization code flow is not configured'
+})()
+
+export const ERR_CODE_SCHEMA = new (class CodeSchemaError extends Error {
+  public readonly code = 'CODE_SCHEMA'
+  public override readonly message = 'Invalid code credentials'
+})()

package/components/identity.federation/source/lib/exchange.ts

@@ -0,0 +1,123 @@
+import { load } from './jose.js'
+import { createRemoteJWKSet, discover } from './discovery.js'
+import * as errors from './errors.js'
+import type { Trust } from '../types/index.js'
+import type { Ctx } from './Ctx.js'
+import type { Payload } from './Payload.js'
+
+export async function exchange(credentials: string, ctx: Ctx): Promise<Payload | Error> {
+  const jose = await load()
+  const properties = decode(credentials)
+
+  if (properties instanceof Error) return properties
+
+  const { code, iss, for: redirect } = properties
+
+  const trusted = ctx.trust.find((trust) => trust.iss === iss)
+
+  if (trusted === undefined) return errors.ERR_TRUST
+
+  if (
+    trusted.aud === undefined ||
+    (trusted.secret === undefined && trusted.signature === undefined)
+  )
+    return errors.ERR_CODE_NOT_ENABLED
+
+  const configuration = await discover(iss, ctx.fetch)
+
+  if (configuration.token_endpoint === undefined) return errors.ERR_CONFIG
+
+  // array actually is not expected here, but it is a valid format
+  const aud = Array.isArray(trusted.aud) ? trusted.aud[0] : trusted.aud
+  const secret =
+    trusted.secret === undefined ? await sign(trusted) : trusted.secret.unwrap()
+  const params = new URLSearchParams()
+
+  params.append('grant_type', 'authorization_code')
+  params.append('code', code)
+  params.append('client_id', aud)
+  params.append('client_secret', secret)
+  params.append('redirect_uri', redirect)
+
+  ctx.logs.debug('Exchanging code', {
+    iss,
+    aud,
+    for: redirect,
+    auth: trusted.secret === undefined ? 'signature' : 'secret'
+  })
+
+  const response = await ctx.fetch(configuration.token_endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded'
+    },
+    body: params
+  })
+
+  if (!response.ok) {
+    ctx.logs.error('Code exchange failed', {
+      status: response.status,
+      text: await response.text()
+    })
+
+    return errors.ERR_RESPONSE
+  }
+
+  const tokens = (await response.json()) as { id_token: string }
+
+  if (tokens.id_token === undefined) return errors.ERR_NO_TOKEN
+
+  const jwks = await createRemoteJWKSet(iss, ctx.fetch)
+
+  try {
+    const { payload } = await jose.jwtVerify(tokens.id_token, jwks, {
+      issuer: iss,
+      audience: trusted.aud,
+      requiredClaims: ['exp']
+    })
+
+    return payload as Payload
+  } catch {
+    return errors.ERR_TOKEN
+  }
+}
+
+function decode(credentials: string): Properties | Error {
+  const json = Buffer.from(credentials, 'base64').toString('utf8')
+  const properties = JSON.parse(json) as Properties
+
+  if (
+    typeof properties.code !== 'string' ||
+    typeof properties.iss !== 'string' ||
+    typeof properties.for !== 'string' ||
+    Object.keys(properties).length !== CREDENTIAL_PROPERTIES.length
+  )
+    return errors.ERR_CODE_SCHEMA
+
+  return properties
+}
+
+async function sign(trust: Trust): Promise<string> {
+  const jose = await load()
+  const signature = trust.signature!
+  const aud = Array.isArray(trust.aud) ? trust.aud[0] : trust.aud!
+  const now = Math.floor(Date.now() / 1000)
+  const key = await jose.importPKCS8(signature.key.unwrap(), 'ES256')
+
+  return await new jose.SignJWT({})
+    .setProtectedHeader({ alg: 'ES256', kid: signature.kid })
+    .setIssuedAt(now)
+    .setExpirationTime(now + 300)
+    .setIssuer(signature.iss)
+    .setSubject(aud)
+    .setAudience(trust.iss)
+    .sign(key)
+}
+
+const CREDENTIAL_PROPERTIES: Array<keyof Properties> = ['for', 'iss', 'code']
+
+interface Properties {
+  code: string
+  iss: string
+  for: string
+}

package/components/identity.federation/source/lib/index.ts

@@ -0,0 +1,5 @@
+export { decode } from './decode.js'
+export { exchange } from './exchange.js'
+export { principal } from './principal.js'
+export { resolve } from './resolve.js'
+export { type Ctx } from './Ctx.js'

package/components/identity.federation/source/lib/jose.d.ts

@@ -0,0 +1 @@
+export function load(): Promise<typeof import('jose')>

package/components/identity.federation/source/lib/jose.js

@@ -0,0 +1 @@
+export const load = async () => await import('jose')

package/components/identity.federation/source/lib/principal.ts

@@ -0,0 +1,19 @@
+import type { Context, Entity } from '../types/index.js'
+
+/**
+ * The `system` Role is granted where the credentials are created, before the reply that mints
+ * a Token from them — the event that carries the same grant lands after it.
+ */
+export async function principal(credential: Entity, context: Context): Promise<void> {
+  const configured = context.configuration.principal
+
+  if (
+    configured === undefined ||
+    configured.authority !== credential.authority ||
+    configured.iss !== credential.iss ||
+    configured.sub !== credential.sub
+  )
+    return
+
+  await context.remote.identity.roles.principal({ input: { id: credential.identity } })
+}

package/components/identity.federation/source/lib/resolve.ts

@@ -0,0 +1,21 @@
+import { decode } from './decode.js'
+import { exchange } from './exchange.js'
+import type { Ctx } from './Ctx.js'
+import type { Payload } from './Payload.js'
+import type { Context, Scheme } from '../types/index.js'
+
+export async function resolve(
+  scheme: Scheme,
+  credentials: string,
+  context: Context
+): Promise<Payload | Error> {
+  const ctx: Ctx = {
+    trust: context.configuration.trust,
+    logs: context.logs,
+    fetch: context.fetch
+  }
+
+  return scheme === 'bearer'
+    ? await decode(credentials, ctx)
+    : await exchange(credentials, ctx)
+}

package/components/identity.federation/source/list.test.ts

@@ -0,0 +1,41 @@
+import { it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
+
+import { computation } from './list.js'
+
+it('lists indexed credentials', async () => {
+  const current = {
+    id: 'credential',
+    authority: 'nex',
+    identity: 'identity',
+    iss: 'apple',
+    sub: '1',
+    CREATED: 2
+  }
+
+  const context = {
+    local: {
+      enumerate: mock.fn(async () => [current])
+    }
+  }
+
+  await assert.deepStrictEqual(
+    await computation({ authority: 'nex', identity: 'identity' }, context as never),
+    [current]
+  )
+  assert.ok(
+    context.local.enumerate.mock.calls.some(
+      (call: any) =>
+        call.arguments.length === 1 &&
+        isDeepStrictEqual(call.arguments[0], {
+          query: {
+            criteria: 'authority=="nex";identity=="identity"',
+            projection: ['iss'],
+            sort: ['CREATED:desc'],
+            limit: 100
+          }
+        })
+    )
+  )
+})

package/components/identity.federation/source/list.ts

@@ -0,0 +1,21 @@
+import { quote } from '@toa.io/generic'
+import type { Context, Entity } from './types/index.js'
+
+export async function computation(
+  { authority, identity }: Input,
+  context: Context
+): Promise<Entity[]> {
+  return await context.local.enumerate({
+    query: {
+      criteria: `authority==${quote(authority)};identity==${quote(identity)}`,
+      projection: ['iss'],
+      sort: ['CREATED:desc'],
+      limit: 100
+    }
+  })
+}
+
+interface Input {
+  authority: string
+  identity: string
+}

package/components/identity.federation/source/types/Scheme.ts

@@ -0,0 +1 @@
+export type Scheme = 'bearer' | 'code'

package/components/identity.federation/source/types/configuration.ts

@@ -1,16 +1,24 @@
+import type { Secret } from '@toa.io/extensions.configuration'
+
 export interface Configuration {
-  trust?: Trust[]
+  trust: Trust[]
   principal?: Principal
-  explicit_identity_creation?: boolean
+  assert?: boolean
 }
 
 export interface Trust {
   iss: string
-  aud?: [string, ...string[]]
-  secrets?: Record<string, Record<string, string>>
+  aud: string | [string, ...string[]]
+  secret?: Secret
+  signature?: {
+    iss: string
+    kid: string
+    key: Secret
+  }
 }
 
 interface Principal {
+  authority: string
   iss: string
   sub: string
 }