@toa.io/extensions.exposition 1.0.0-alpha.31 → 1.0.0-alpha.310

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

@@ -0,0 +1,123 @@
+import { load } from './jose.js'
+import { createRemoteJWKSet, discover } from './discovery.ts'
+import * as errors from './errors.ts'
+import type { Trust } from '../types/index.ts'
+import type { Ctx } from './Ctx.ts'
+import type { Payload } from './Payload.ts'
+
+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.ts'
+export { exchange } from './exchange.ts'
+export { principal } from './principal.ts'
+export { resolve } from './resolve.ts'
+export { type Ctx } from './Ctx.ts'

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.ts'
+
+/**
+ * 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.ts'
+import { exchange } from './exchange.ts'
+import type { Ctx } from './Ctx.ts'
+import type { Payload } from './Payload.ts'
+import type { Context, Scheme } from '../types/index.ts'
+
+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.ts

@@ -0,0 +1,21 @@
+import { quote } from '@toa.io/generic'
+import type { Context, Entity } from './types/index.ts'
+
+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
 }

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

@@ -1,61 +1,45 @@
-import { type Call, type Observation, type Query } from '@toa.io/types'
-import type { Entity } from './entity'
-import type { Configuration } from './configuration'
+import type { JWTPayload } from 'jose'
+import type { Call, Observation, Query, Transition } from '@toa.io/core/types'
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type { Entity } from './entity.ts'
+import type { Configuration } from './configuration.ts'
 
 export interface Context {
+  fetch: Fetch
   local: {
-    observe: Observation<Entity & { id: string }>
-    transit: Call<TransitOutput, TransitInput>
+    observe: Observation<Entity>
+    enumerate: Observation<Entity[], never, Entity>
+    terminate: Transition<void, void, Entity>
+    transit: Call<Entity, TransitInput>
+    ensure: Call<Entity>
+    decode: Call<JWTPayload, string>
   }
   remote: {
     identity: {
       tokens: {
         revoke: Call<void, IdentityTokensRevokeInput>
       }
+      roles: {
+        principal: Call<void, { id: string }>
+      }
     }
   }
+  logs: Logs
   configuration: Configuration
 }
 
+export type Fetch = (
+  input: string | URL | Request,
+  init?: RequestInit
+) => Promise<Response>
+
 export interface TransitInput {
   readonly authority: string
   readonly iss: string
   readonly sub: string
-}
-
-export interface TransitOutput {
-  id: string
+  readonly identity: string
 }
 
 interface IdentityTokensRevokeInput {
   query: Query
 }
-
-export interface JwtHeader {
-  typ?: string
-  alg: string
-  kid?: string
-}
-
-/**
- * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#IDToken}
- */
-export interface IdToken {
-  iss: string
-  sub: string
-  aud: string
-  exp: number
-  iat: number
-  nbf?: number
-}
-
-export interface AuthenticateInput {
-  authority: string
-  credentials: string
-}
-
-export interface AuthenticateOutput {
-  identity: {
-    id: string
-  }
-}

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

@@ -3,4 +3,7 @@ export interface Entity {
   authority: string
   iss: string
   sub: string
+  identity: string
+  CREATED: number
+  DELETED?: number | null
 }

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

@@ -1,3 +1,4 @@
-export * from './configuration'
-export * from './context'
-export * from './entity'
+export * from './configuration.ts'
+export * from './context.ts'
+export * from './entity.ts'
+export * from './Scheme.ts'

package/components/identity.federation/tsconfig.json

@@ -1,7 +1,8 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../../../tsconfig.component.json",
   "compilerOptions": {
-    "outDir": "./operations"
+    "outDir": "./operations",
+    "rootDir": "./source"
   },
   "include": [
     "source"

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

@@ -0,0 +1,3 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/identity.federation/types/toa.d.ts

@@ -0,0 +1,128 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { Options, Query, RemoteError } from '@toa.io/core/types'
+import type { Secret } from '@toa.io/extensions.configuration'
+import type { FetchInit } from '@toa.io/extensions.fetch'
+import type { Logs, Metrics, Span } from '@toa.io/extensions.telemetry'
+import type { Readable } from 'node:stream'
+
+export interface Entity {
+  /** The authority token is valid for */
+  authority: string
+  /** The issuer, or signer, of the token, URI like `https://accounts.google.com` */
+  iss: string
+  /** The ID that represents the principal making the request */
+  sub: string
+  /** Identity associated with these credentials */
+  identity: string
+  id: string
+  VERSION: number
+  CREATED: number
+  UPDATED: number
+  DELETED: number | null
+  REGION: number
+}
+
+export type TransitInput = {
+  authority: string
+  iss: string
+  sub: string
+  identity: string
+}
+
+export type CreateInput = {
+  scheme: "bearer" | "code"
+  authority: string
+  credentials: string
+  id: string
+}
+
+export type InceptInput = {
+  scheme: "bearer" | "code"
+  authority: string
+  credentials: string
+  id: string
+}
+
+export type InceptOutput = {
+  id?: string
+}
+
+export type AuthenticateInput = {
+  scheme: "bearer" | "code"
+  authority: string
+  credentials: string
+}
+
+export type AuthenticateOutput = {
+  identity?: {
+    id: string
+    claims: {
+      iss: string
+      aud?: string
+      sub: string
+      [key: string]: unknown
+    }
+  }
+}
+
+export type DecodeInput = string
+
+export type DecodeOutput = {
+  iss: string
+  aud?: string
+  sub: string
+  [key: string]: unknown
+}
+
+export type ListInput = {
+  authority: string
+  identity: string
+}
+
+export type DeleteInput = {
+  authority: string
+  identity: string
+  credential: string
+}
+
+export interface Component {
+  transit: (request: { input: TransitInput, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Entity>
+  create: (request: { input: CreateInput, task?: boolean }, options?: Options) => Promise<unknown | RemoteError<"EXISTS" | "TOKEN" | "TRUST" | "RESPONSE" | "CONFIG" | "NO_TOKEN" | "ISS" | "SUB" | "EXP" | "REPLAY" | "CODE_NOT_ENABLED" | "CODE_SCHEMA">>
+  incept: (request: { input: InceptInput, task?: boolean }, options?: Options) => Promise<InceptOutput | RemoteError<"EXISTS" | "TOKEN" | "TRUST" | "RESPONSE" | "CONFIG" | "NO_TOKEN" | "ISS" | "SUB" | "EXP" | "REPLAY" | "CODE_NOT_ENABLED" | "CODE_SCHEMA">>
+  authenticate: (request: { input: AuthenticateInput, task?: boolean }, options?: Options) => Promise<AuthenticateOutput | RemoteError<"NOT_FOUND" | "TOKEN" | "TRUST" | "RESPONSE" | "CONFIG" | "NO_TOKEN" | "ISS" | "SUB" | "EXP" | "REPLAY" | "CODE_NOT_ENABLED" | "CODE_SCHEMA">>
+  decode: (request: { input: DecodeInput, task?: boolean }, options?: Options) => Promise<DecodeOutput>
+  list: (request: { input: ListInput, task?: boolean }, options?: Options) => Promise<unknown>
+  delete: (request: { input: DeleteInput, task?: boolean }, options?: Options) => Promise<unknown>
+  assign: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Entity>
+  ensure: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Entity>
+  enumerate: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Entity[]>
+  observe: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Entity | null>
+  stream: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Readable>
+  terminate: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<Entity>
+}
+
+export interface Configuration {
+  trust?: Array<{
+    /** Allowed values for a token `iss` field */
+    iss: string
+    /** Acceptable `aud` value(s) */
+    aud: string | string[]
+    signature?: {
+      iss: string
+      kid: string
+      /** PKCS8 private key in PEM form */
+      key: string
+    }
+    /** Client secret for the Identity Provider. Required for Authorization Code Flow. */
+    secret?: string
+  }>
+  /** Subject that will be assigned the `system` Role */
+  principal?: {
+    authority: string
+    iss: string
+    sub: string
+  }
+  assert?: boolean
+}