@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.300

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.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

@@ -0,0 +1,24 @@
+import type { Secret } from '@toa.io/extensions.configuration'
+
+export interface Configuration {
+  trust: Trust[]
+  principal?: Principal
+  assert?: boolean
+}
+
+export interface Trust {
+  iss: 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

@@ -0,0 +1,45 @@
+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.js'
+import type { Configuration } from './configuration.js'
+
+export interface Context {
+  fetch: Fetch
+  local: {
+    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
+  readonly identity: string
+}
+
+interface IdentityTokensRevokeInput {
+  query: Query
+}

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

@@ -0,0 +1,9 @@
+export interface Entity {
+  id: string
+  authority: string
+  iss: string
+  sub: string
+  identity: string
+  CREATED: number
+  DELETED?: number | null
+}

package/components/identity.federation/source/types/index.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/tsconfig.json

@@ -1,9 +1,10 @@
 {
-  "extends": "../../tsconfig.json",
+  "extends": "../../../../tsconfig.component.json",
   "compilerOptions": {
     "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, 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
+}

package/components/identity.grants/manifest.toa.yaml

@@ -0,0 +1,241 @@
+namespace: identity
+name: grants
+
+# What a user allowed a client to do on their behalf. The authorization code is not here:
+# it is single-use and lives seconds, so it is held in the stash and redeemed atomically.
+entity:
+  associated: true
+  properties:
+    authority:
+      type: string
+    identity:
+      type: string
+    client:
+      type: string
+    scope:
+      type: array
+      items:
+        type: string
+    resource:
+      type: array
+      items:
+        type: string
+    kid:
+      description: The identity.keys record backing the access token, revoked with the grant
+      type: string
+    revokedAt:
+      type: integer
+  required:
+    - authority
+    - identity
+    - client
+
+operations:
+  transit:
+    concurrency: retry
+    input:
+      type: object
+      properties:
+        authority:
+          type: string
+        identity:
+          type: string
+        client:
+          type: string
+        scope:
+          type: array
+          items:
+            type: string
+        resource:
+          type: array
+          items:
+            type: string
+        kid:
+          type: string
+      required:
+        - authority
+        - identity
+        - client
+
+  authorize:
+    query: false
+    input:
+      type: object
+      properties:
+        authority:
+          type: string
+        identity:
+          type: string
+        client:
+          type: string
+          maxLength: 2048
+        redirect:
+          type: string
+          maxLength: 2048
+        challenge:
+          description: PKCE code challenge, S256 of the verifier
+          type: string
+          minLength: 43
+          maxLength: 128
+        method:
+          type: string
+        scope:
+          type: array
+          items:
+            type: string
+        resource:
+          type: array
+          items:
+            type: string
+            maxLength: 2048
+      required:
+        - authority
+        - identity
+        - client
+        - redirect
+        - challenge
+        - method
+    output:
+      type: object
+      properties:
+        status:
+          description: Read and removed by `io:status`
+          type: number
+        code:
+          type: string
+        expires_in:
+          type: number
+        error:
+          type: string
+        error_description:
+          type: string
+
+  exchange:
+    query: false
+    input:
+      type: object
+      properties:
+        authority:
+          type: string
+        grant_type:
+          type: string
+        code:
+          type: string
+          maxLength: 512
+        code_verifier:
+          type: string
+          minLength: 43
+          maxLength: 128
+        redirect_uri:
+          type: string
+          maxLength: 2048
+        client_id:
+          type: string
+          maxLength: 2048
+        resource:
+          description: A form repeats a name to say a list, so either shape arrives
+          type: [string, array]
+      required:
+        - authority
+        - grant_type
+    output:
+      type: object
+      properties:
+        status:
+          type: number
+        access_token:
+          type: string
+        token_type:
+          type: string
+        expires_in:
+          type: number
+        scope:
+          type: string
+        error:
+          type: string
+        error_description:
+          type: string
+
+  list:
+    input:
+      type: object
+      properties:
+        authority:
+          type: string
+        identity:
+          type: string
+      required:
+        - authority
+        - identity
+
+  revoke:
+    output: { type: 'null' }
+    concurrency: retry
+    input:
+      type: object
+      properties:
+        authority:
+          type: string
+        identity:
+          type: string
+      required:
+        - authority
+        - identity
+    errors:
+      - NOT_FOUND
+
+configuration:
+  schema:
+    type: object
+    properties:
+      lifetime:
+        description: Seconds an authorization code may be redeemed within
+        type: integer
+        minimum: 1
+        maximum: 600
+      token:
+        description: Seconds an access token is valid for; 0 is until it is revoked
+        type: integer
+        minimum: 0
+    # both have defaults, so the component reads them without checking
+    required: [lifetime, token]
+
+  defaults:
+    lifetime: 60
+    token: 2592000
+
+stash: ~
+
+exposition:
+  isolated: true
+  /:
+    POST:
+      anonymous: true
+      map:authority: authority
+      io:input: [grant_type, code, code_verifier, redirect_uri, client_id, resource]
+      io:output: true
+      io:status: status
+      io:throttle:
+        key: ip
+        requests: 60
+        interval: 60
+      cache:exact: no-store
+      endpoint: exchange
+    /:identity:
+      auth:id: identity
+      map:authority: authority
+      map:segments:
+        identity: identity
+      GET:
+        io:output: [id, client, scope, resource, CREATED]
+        endpoint: list
+      POST:
+        io:input: [client, redirect, challenge, method, scope, resource]
+        io:output: [code, expires_in, error, error_description]
+        io:status: status
+        cache:exact: no-store
+        endpoint: authorize
+      /:id:
+        DELETE:
+          io:output: false
+          endpoint: revoke

package/components/identity.grants/migrations/0002-indexes.yaml

@@ -0,0 +1,5 @@
+- index:
+    name: index_identity
+    keys:
+      authority: asc
+      identity: asc