@toa.io/extensions.exposition 1.0.0-alpha.28 → 1.0.0-alpha.282

package/components/identity.federation/operations/types/entity.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entity.js.map

package/components/identity.federation/operations/types/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../source/types/entity.ts"],"names":[],"mappings":""}

package/components/identity.federation/operations/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './configuration.js';
+export * from './context.js';
+export * from './entity.js';
+export * from './Scheme.js';

package/components/identity.federation/operations/types/index.js

@@ -0,0 +1,5 @@
+export * from './configuration.js';
+export * from './context.js';
+export * from './entity.js';
+export * from './Scheme.js';
+//# sourceMappingURL=index.js.map

package/components/identity.federation/operations/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

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

@@ -1,31 +1,52 @@
-import { type Maybe } from '@toa.io/types'
-import { Err } from 'error-value'
-import { assertionsAsValues } from './lib/assertions-as-values.js'
-import {
-  validateIdToken
-} from './lib/jwt'
-import type { AuthenticateInput, AuthenticateOutput, Context } from './types'
-import type { Request } from '@toa.io/core'
+import { newid, quote } from '@toa.io/generic'
+import { resolve } from './lib/index.js'
+import type { JWTPayload } from 'jose'
+import type { Maybe } from '@toa.io/types'
+import type { Context, Scheme } from './types/index.js'
 
-async function authenticate ({ authority, credentials }: AuthenticateInput,
-  context: Context): Promise<Maybe<AuthenticateOutput>> {
-  const { iss, sub } = await validateIdToken(credentials, context.configuration.trust)
+export async function effect ({ scheme, authority, credentials }: Input, context: Context): Promise<Maybe<Output>> {
+  context.logs.debug('Authenticating', { scheme, authority })
 
-  const request: Request = { query: { criteria: `authority==${authority};iss==${iss};sub==${sub}` } }
+  const claims = await resolve(scheme, credentials, context)
 
-  let id = (await context.local.observe(request))?.id
+  if (claims instanceof Error)
+    return claims
 
-  if (id === undefined) {
-    if (context.configuration.explicit_identity_creation === true)
-      return NOT_FOUND
+  const { iss, sub } = claims
 
-    id = (await context.local.transit({ input: { authority, iss, sub } })).id
-  }
+  context.logs.debug('Token claims', claims)
+
+  const query = { criteria: `authority==${quote(authority)};iss==${quote(iss)};sub==${quote(sub)}` }
+
+  const credential = context.configuration.assert !== false
+    ? await context.local.ensure({
+      query,
+      entity: { authority, iss, sub, identity: newid() }
+    })
+    : await context.local.observe({ query })
+
+  if (credential === null)
+    return ERR_NOT_FOUND
+
+  if (credential instanceof Error)
+    return credential
 
-  return { identity: { id } }
+  return { identity: { id: credential.identity, claims } }
 }
 
-// Exporting as a function returning assertion errors as values
-export const computation = assertionsAsValues(authenticate)
+const ERR_NOT_FOUND = new (class NotFoundError extends Error {
+  public readonly code = 'NOT_FOUND'
+})()
 
-const NOT_FOUND = Err('NOT_FOUND')
+interface Input {
+  scheme: Scheme
+  authority: string
+  credentials: string
+}
+
+interface Output {
+  identity: {
+    id: string
+    claims: JWTPayload
+  }
+}

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

@@ -0,0 +1,45 @@
+import { quote } from '@toa.io/generic'
+import { resolve } from './lib/index.js'
+import type { Context, Entity, Scheme } from './types/index.js'
+
+export async function effect (input: Input, context: Context): Promise<Entity | Error> {
+  const claims = await resolve(input.scheme, input.credentials, context)
+
+  if (claims instanceof Error)
+    return claims
+
+  const { iss, sub } = claims
+
+  const existent = await context.local.observe({
+    query: {
+      criteria: `authority==${quote(input.authority)};iss==${quote(iss)};sub==${quote(sub)}`,
+      deleted: true
+    }
+  })
+
+  const record = { authority: input.authority, iss, sub, identity: input.id }
+
+  if (existent === null)
+    return await context.local.transit({ input: record })
+
+  if (existent._deleted === undefined || existent._deleted === null)
+    return existent.identity === input.id ? existent : ERR_EXISTS
+
+  // a deleted record still occupies the unique index, so the transition revives it
+  return await context.local.transit({
+    input: record,
+    query: { id: existent.id, deleted: true }
+  })
+}
+
+export interface Input {
+  authority: string
+  scheme: Scheme
+  credentials: string
+  id: string
+}
+
+const ERR_EXISTS = new (class ExistsError extends Error {
+  public readonly code = 'EXISTS'
+  public override readonly message = 'Federation credentials are associated with another Identity'
+})()

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

@@ -0,0 +1,11 @@
+import { decode } from './lib/index.js'
+import type { JWTPayload } from 'jose'
+import type { Context } from './types/index.js'
+
+export async function effect (token: string, context: Context): Promise<JWTPayload | Error> {
+  return await decode(token, {
+    trust: context.configuration.trust,
+    logs: context.logs,
+    fetch: context.fetch
+  })
+}

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

@@ -0,0 +1,16 @@
+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,19 @@
-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 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 (input.id !== undefined)
-    request.query = { id: input.id }
-
-  return await context.local.transit(request)
+  return credential instanceof Error ? credential : { 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 { telemetry } from '@toa.io/types'
+import type { Trust } from '../types/index.js'
+import type { Fetch } from '../types/context.js'
+
+export interface Ctx {
+  trust: Trust[]
+  logs: telemetry.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,31 @@
+import { load } from './jose.js'
+import { createRemoteJWKSet } from './discovery.js'
+import { ERR_TRUST, ERR_ISS, ERR_SUB } from './errors.js'
+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()
+  const { iss, sub } = jose.decodeJwt(token)
+
+  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
+
+  const jwks = await createRemoteJWKSet(iss, ctx.fetch)
+
+  const { payload } = await jose.jwtVerify(token, jwks, {
+    issuer: iss,
+    audience: trusted.aud,
+    requiredClaims: ['exp']
+  })
+
+  return payload as Payload
+}

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

@@ -0,0 +1,50 @@
+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,49 @@
+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,49 @@
+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,116 @@
+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)
+
+  const { payload } = await jose.jwtVerify(tokens.id_token, jwks, {
+    issuer: iss,
+    audience: trusted.aud,
+    requiredClaims: ['exp']
+  })
+
+  return payload as Payload
+}
+
+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,4 @@
+export { decode } from './decode.js'
+export { exchange } from './exchange.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/resolve.ts

@@ -0,0 +1,17 @@
+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,25 @@
+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,18 @@
+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'