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

package/components/identity.tokens/source/decrypt.ts

@@ -1,33 +1,195 @@
-import { V3 } from 'paseto'
-import { type Maybe } from '@toa.io/types'
-import { type Context, type Claim, type DecryptOutput } from './types'
-
-export async function computation (token: string, context: Context):
-Promise<Maybe<DecryptOutput>> {
-  let refresh = false
-  let claim = await decrypt(token, context.configuration.key0)
-
-  if (claim === null && context.configuration.key1 !== undefined) {
-    refresh = true
-    claim = await decrypt(token, context.configuration.key1)
+import { DecryptFactory, ImportKeyFactory } from 'paseto/v3/local'
+import { LRUCache } from 'lru-cache'
+import { form, jweKey } from './lib/index.js'
+import { load } from './lib/jose.js'
+import type { Maybe } from '@toa.io/core/types'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Claims, DecryptOutput, JWEClaims } from './lib/index.js'
+
+export class Computation implements Operation {
+  private readonly keys: Record<string, Key> = {}
+  private readonly legacy: Record<string, Key> = {}
+  private cache!: LRUCache<string, KeyEntry>
+  private latest!: string
+  private remote!: Context['remote']['identity']['keys']
+  private logs!: Context['logs']
+
+  public mount(context: Context): void {
+    const latest = context.configuration.keys.find(({ format }) => format !== 'paseto')
+
+    if (latest === undefined)
+      throw new TypeError('At least one JWE key must be configured')
+
+    this.latest = latest.id
+    this.remote = context.remote.identity.keys
+    this.cache = new LRUCache<string, KeyEntry>(context.configuration.cache)
+    this.logs = context.logs
+
+    for (const { id, key, format } of context.configuration.keys) {
+      const branch = format === 'paseto' ? this.legacy : this.keys
+
+      branch[id] = { key: key.unwrap() }
+    }
+  }
+
+  public async execute(token: string): Promise<Maybe<DecryptOutput>> {
+    const legacy = form(token) === 'paseto'
+    const kid = legacy ? this.pasetoKid(token) : await this.jweKid(token)
+
+    if (kid instanceof Error) return kid
+
+    const key = await this.key(kid, legacy)
+
+    if (key instanceof Error) return key
+
+    const claims = legacy
+      ? await decryptPaseto(token, key.key)
+      : await decryptJWE(token, key.key)
+
+    if (claims instanceof Error) return claims
+
+    this.logs.debug('Token claims', claims)
+
+    if (key.identity !== undefined && claims.identity.id !== key.identity)
+      return ERR_FORGED_KEY
+
+    if (key.revokedAt !== undefined) return ERR_REVOKED_KEY
+
+    return {
+      iss: claims.iss,
+      iat: claims.iat,
+      exp: claims.exp,
+      identity: claims.identity,
+      ...(claims.aud === undefined ? {} : { aud: claims.aud }),
+      refresh: legacy || (kid !== this.latest && key.identity === undefined),
+      custom: key.identity !== undefined
+    }
   }
 
-  if (claim === null)
+  private pasetoKid(token: string): Maybe<string> {
+    const [, , , footer] = token.split('.')
+
+    if (footer === undefined) return ERR_INVALID_TOKEN
+
+    try {
+      const json = Buffer.from(footer, 'base64url').toString('utf-8')
+      const { kid } = JSON.parse(json)
+
+      if (typeof kid !== 'string') return ERR_INVALID_TOKEN
+
+      return kid
+    } catch {
+      return ERR_INVALID_TOKEN
+    }
+  }
+
+  private async jweKid(token: string): Promise<Maybe<string>> {
+    try {
+      const { decodeProtectedHeader } = await load()
+      const header = decodeProtectedHeader(token)
+
+      if (
+        header.alg !== 'dir' ||
+        header.enc !== 'A256GCM' ||
+        header.typ !== 'JWT' ||
+        typeof header.kid !== 'string'
+      )
+        return ERR_INVALID_TOKEN
+
+      return header.kid
+    } catch {
+      return ERR_INVALID_TOKEN
+    }
+  }
+
+  private async key(kid: string, legacy: boolean): Promise<Maybe<Key>> {
+    const configured = legacy ? this.legacy : this.keys
+
+    if (kid in configured) return configured[kid]
+
+    if (!this.cache.has(kid)) {
+      const value = await this.remote.observe({ query: { id: kid } })
+
+      this.cache.set(kid, { value })
+    }
+
+    const entry = this.cache.get(kid)
+
+    return entry?.value ?? ERR_INVALID_KEY
+  }
+}
+
+async function decryptPaseto(token: string, key: string): Promise<Maybe<Claims>> {
+  try {
+    const secret = await importKey(key as `k3.local.${string}`)
+    // paseto 3 read a token that never expires; these are tokens already in the wild
+    const { claims } = await decryptLocal(secret, token, { allowNonExpiring: true })
+
+    return claims as unknown as Claims
+  } catch {
     return ERR_INVALID_TOKEN
-  else return {
-    identity: claim.identity,
-    iat: claim.iat,
-    exp: claim.exp,
-    refresh
   }
 }
 
-async function decrypt (token: string, key: string): Promise<Claim | null> {
+async function decryptJWE(token: string, key: string): Promise<Maybe<Claims>> {
   try {
-    return await V3.decrypt<Claim>(token, key)
+    const { jwtDecrypt } = await load()
+
+    const { payload } = await jwtDecrypt<JWEClaims>(token, jweKey(key), {
+      keyManagementAlgorithms: ['dir'],
+      contentEncryptionAlgorithms: ['A256GCM']
+    })
+
+    if (
+      typeof payload.iss !== 'string' ||
+      typeof payload.iat !== 'number' ||
+      typeof payload.identity !== 'object' ||
+      payload.identity === null
+    )
+      return ERR_INVALID_TOKEN
+
+    if (payload.exp !== undefined && payload.exp * 1000 <= Date.now())
+      return ERR_INVALID_TOKEN
+
+    return {
+      iss: payload.iss,
+      iat: new Date(payload.iat * 1000).toISOString(),
+      ...(payload.exp === undefined
+        ? {}
+        : { exp: new Date(payload.exp * 1000).toISOString() }),
+      identity: payload.identity,
+      ...(payload.aud === undefined ? {} : { aud: payload.aud })
+    }
   } catch {
-    return null
+    return ERR_INVALID_TOKEN
   }
 }
 
-const ERR_INVALID_TOKEN = new Error('INVALID_TOKEN')
+const importKey = ImportKeyFactory().run
+const decryptLocal = DecryptFactory().run
+
+interface Key {
+  key: string
+  identity?: string
+  revokedAt?: number
+}
+
+interface KeyEntry {
+  value: Key | null
+}
+
+const ERR_INVALID_TOKEN = new (class InvalidTokenError extends Error {
+  public readonly code = 'INVALID_TOKEN'
+})()
+
+const ERR_INVALID_KEY = new (class InvalidKeyError extends Error {
+  public readonly code = 'INVALID_KEY'
+})()
+
+const ERR_FORGED_KEY = new (class ForgedKeyError extends Error {
+  public readonly code = 'FORGED_KEY'
+})()
+
+const ERR_REVOKED_KEY = new (class RevokedKeyError extends Error {
+  public readonly code = 'REVOKED_KEY'
+})()

package/components/identity.tokens/source/encrypt.ts

@@ -1,25 +1,61 @@
-import { V3 } from 'paseto'
-import { type Operation } from '@toa.io/types'
-import { type Claim, type Context, type EncryptInput } from './types'
+import { jweKey } from './lib/index.js'
+import { load } from './lib/jose.js'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Maybe } from '@toa.io/core/types'
+import type { Identity, Context, EncryptInput, Key } from './lib/index.js'
 
 export class Effect implements Operation {
-  private key: string = ''
-  private lifetime: number = 0
+  private key!: Pick<Key, 'id' | 'key'>
+  private lifetime!: number
 
-  public mount (context: Context): void {
-    this.key = context.configuration.key0
+  public mount(context: Context): void {
+    const key = context.configuration.keys.find(({ format }) => format !== 'paseto')
+
+    if (key === undefined) throw new TypeError('At least one JWE key must be configured')
+
+    this.key = { id: key.id, key: key.key.unwrap() }
     this.lifetime = context.configuration.lifetime * 1000
   }
 
-  public async execute (input: EncryptInput): Promise<string> {
+  public async execute(input: EncryptInput): Promise<Maybe<string>> {
+    const { EncryptJWT } = await load()
+
+    if (input.scopes?.some((scope) => !within(scope, input.identity.roles)) === true)
+      return ERR_INACCESSIBLE_SCOPE
+
     const lifetime = input.lifetime === undefined ? this.lifetime : input.lifetime * 1000
 
-    const exp = lifetime === 0
-      ? undefined
-      : new Date(Date.now() + lifetime).toISOString()
+    const identity: Identity = {
+      id: input.identity.id,
+      roles: input.scopes ?? input.identity.roles
+    }
+
+    const permissions = input.permissions ?? input.identity.permissions
+
+    if (permissions !== undefined) identity.permissions = permissions
 
-    const payload: Partial<Claim> = { identity: input.identity, exp }
+    const key = input.key ?? this.key
 
-    return await V3.encrypt(payload, this.key)
+    let token = new EncryptJWT({ identity })
+      .setProtectedHeader({ alg: 'dir', enc: 'A256GCM', typ: 'JWT', kid: key.id })
+      .setIssuer(input.authority)
+      .setIssuedAt(Date.now() / 1000)
+
+    if (input.audience !== undefined && input.audience.length > 0)
+      token = token.setAudience(
+        input.audience.length === 1 ? input.audience[0] : input.audience
+      )
+
+    if (lifetime !== 0) token = token.setExpirationTime((Date.now() + lifetime) / 1000)
+
+    return await token.encrypt(jweKey(key.key))
   }
 }
+
+function within(scope: string, roles: string[]): boolean {
+  return roles.some((role) => role === scope || scope.startsWith(role + ':'))
+}
+
+const ERR_INACCESSIBLE_SCOPE = new (class InaccessibleScopeError extends Error {
+  public readonly code = 'INACCESSIBLE_SCOPE'
+})()

package/components/identity.tokens/source/issue.ts

@@ -0,0 +1,85 @@
+import { quote } from '@toa.io/generic'
+import type { Maybe } from '@toa.io/core/types'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Identity } from './lib/index.js'
+
+export class Effect implements Operation {
+  private keys!: Context['remote']['identity']['keys']
+  private roles!: Context['remote']['identity']['roles']
+  private encrypt!: Context['local']['encrypt']
+  private lifetime!: number
+
+  public mount(context: Context): void {
+    this.keys = context.remote.identity.keys
+    this.roles = context.remote.identity.roles
+    this.encrypt = context.local.encrypt
+    // seconds, as `input.lifetime` and `encrypt` both are
+    this.lifetime = context.configuration.lifetime
+  }
+
+  public async execute(input: Input): Promise<Maybe<Output>> {
+    const lifetime = input.lifetime ?? this.lifetime
+
+    const expires =
+      lifetime === 0 ? undefined : new Date(Date.now() + lifetime * 1000).getTime()
+
+    const key = await this.keys.create({
+      input: {
+        identity: input.identity,
+        label: input.label,
+        expires
+      }
+    })
+
+    const roles = await this.roles.list({
+      query: {
+        criteria: `identity==${quote(input.identity)}`,
+        limit: 1024
+      }
+    })
+
+    const identity: Identity = {
+      id: input.identity,
+      roles
+    }
+
+    const { authority, scopes, permissions, audience } = input
+
+    const token = await this.encrypt({
+      input: {
+        authority,
+        identity,
+        lifetime,
+        scopes,
+        permissions,
+        audience,
+        key
+      }
+    })
+
+    if (token instanceof Error) return token
+
+    return {
+      kid: key.id,
+      // technically, the token expires some time later
+      ...(expires !== undefined && { exp: expires }),
+      token
+    }
+  }
+}
+
+interface Input {
+  authority: string
+  identity: string
+  label: string
+  lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  audience?: string[]
+}
+
+interface Output {
+  kid: string
+  exp?: number
+  token: string
+}

package/components/identity.tokens/source/lib/form.ts

@@ -0,0 +1,27 @@
+/**
+ * The form of a token this component issues, or nothing for a credential it did not:
+ * a compact JWE has five segments, where a JWS — an OpenID `id_token`, say — has three.
+ * Read without decrypting, and without trusting: a credential that lies about its form
+ * only reaches a verifier that rejects it.
+ */
+export function form(token: string): Form | null {
+  if (token.startsWith(PASETO)) return 'paseto'
+
+  if (segments(token) === JWE_SEGMENTS) return 'jwe'
+
+  return null
+}
+
+function segments(token: string): number {
+  let count = 1
+
+  for (let i = 0; i < token.length; i++) if (token.charCodeAt(i) === DOT) count++
+
+  return count
+}
+
+const PASETO = 'v3.local.'
+const JWE_SEGMENTS = 5
+const DOT = 46
+
+export type Form = 'paseto' | 'jwe'

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

@@ -0,0 +1,4 @@
+export * from './form.js'
+export * from './pad.js'
+export type * from '../../types/index.js'
+export { jweKey } from './key.js'

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

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

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

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

package/components/identity.tokens/source/lib/key.ts

@@ -0,0 +1,8 @@
+export function jweKey(value: string): Uint8Array {
+  const key = Buffer.from(value, 'base64url')
+
+  if (key.length !== 32 || key.toString('base64url') !== value)
+    throw new TypeError('JWE key must be a base64url-encoded 256-bit secret')
+
+  return new Uint8Array(key)
+}

package/components/identity.tokens/source/lib/pad.ts

@@ -0,0 +1 @@
+export const PAD = 'v3.local.'

package/components/identity.tokens/source/revoke.ts

@@ -1,5 +1,5 @@
-import { type Entity } from './types'
+import type { Entity } from './lib/index.js'
 
-export function transition (_: never, object: Entity): void {
+export function transition(_: unknown, object: Entity): void {
   object.revokedAt = Date.now()
 }

package/components/identity.tokens/tsconfig.json

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

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

@@ -0,0 +1,71 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.
+
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type {
+  AuthenticateOutput,
+  Component,
+  Configuration,
+  DecryptOutput
+} from './toa.js'
+
+/** Who the token is for, as it travels: the claim set the gateway is written against. */
+export type Identity = AuthenticateOutput['identity']
+
+/** A key as it is configured: the secret and the form it is used in. */
+export type ConfiguredKey = Configuration['keys'][number]
+
+/** A key as `identity.keys` keeps it. */
+export interface Key {
+  id: string
+  key: string
+  label: string
+}
+
+/** A key issued for one identity, which revoking it invalidates every token under. */
+export interface CustomKey extends Key {
+  identity: string
+  revokedAt?: number
+}
+
+/** What a token carries, before it is encoded. */
+export interface Claims {
+  identity: Identity
+  iss: string
+  iat: string
+  exp?: string
+  aud?: string | string[]
+}
+
+/** The same, as JWE writes the times. */
+export interface JWEClaims extends Omit<Claims, 'iat' | 'exp'> {
+  iat: number
+  exp?: number
+}
+
+/** What this component is given: its own operations, and the two it reads keys and roles from. */
+export interface Context {
+  local: Component
+  remote: {
+    identity: {
+      keys: {
+        observe: (request: {
+          query: { id?: string; criteria?: string }
+        }) => Promise<CustomKey | null>
+        create: (request: {
+          input: { identity: string; label?: string; expires?: number }
+        }) => Promise<Key>
+      }
+      roles: {
+        list: (request: {
+          query: { criteria: string; limit?: number }
+        }) => Promise<string[]>
+      }
+    }
+  }
+  configuration: Configuration
+  logs: Logs
+}
+
+export type { DecryptOutput }

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

@@ -0,0 +1,120 @@
+// 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 {
+  revokedAt?: number
+  id: string
+  VERSION: number
+  CREATED: number
+  UPDATED: number
+  DELETED: number | null
+  REGION: number
+}
+
+export type EncryptInput = {
+  lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  /** Resource URIs this token may be presented at (RFC 8707) */
+  audience?: string[]
+  key?: {
+    id: string
+    key: string
+  }
+  authority: string
+  identity: {
+    id: string
+    roles: string[]
+    [key: string]: unknown
+  }
+}
+
+export type EncryptOutput = string
+
+export type DecryptInput = string
+
+export type DecryptOutput = {
+  /** The authority the token names as its issuer */
+  iss: string
+  identity: {
+    id: string
+    roles: string[]
+    [key: string]: unknown
+  }
+  iat: string
+  exp?: string
+  /** Resource URIs this token may be presented at */
+  aud?: string | unknown[]
+  custom: boolean
+  refresh: boolean
+}
+
+export type AuthenticateInput = {
+  authority: string
+  credentials: string
+}
+
+export type AuthenticateOutput = {
+  identity: {
+    id: string
+    roles: string[]
+    [key: string]: unknown
+  }
+  refresh: boolean
+}
+
+export type IssueInput = {
+  authority: string
+  identity: string
+  lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  /** Resource URIs this token may be presented at (RFC 8707) */
+  audience?: string[]
+  label: string
+}
+
+export type IssueOutput = {
+  kid: string
+  exp?: number
+  token: string
+}
+
+export type RevokeOutput = null
+
+export interface Component {
+  encrypt: (request: { input: EncryptInput, task?: boolean }, options?: Options) => Promise<EncryptOutput | RemoteError<"INACCESSIBLE_SCOPE">>
+  decrypt: (request: { input: DecryptInput, task?: boolean }, options?: Options) => Promise<DecryptOutput | RemoteError<"INVALID_TOKEN" | "INVALID_KEY" | "FORGED_KEY" | "REVOKED_KEY">>
+  authenticate: (request: { input: AuthenticateInput, task?: boolean }, options?: Options) => Promise<AuthenticateOutput | RemoteError<"UNRECOGNIZED" | "AUTHORITY_MISMATCH" | "TOKEN_REVOKED" | "INVALID_TOKEN" | "INVALID_KEY" | "FORGED_KEY" | "REVOKED_KEY">>
+  issue: (request: { input: IssueInput, task?: boolean }, options?: Options) => Promise<IssueOutput | RemoteError<"INACCESSIBLE_SCOPE">>
+  revoke: (request: { input?: null, query?: Query<Entity>, task?: boolean }, options?: Options) => Promise<RevokeOutput>
+  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 {
+  keys: Array<{
+    id: string
+    key: Secret
+    format?: "jwe" | "paseto"
+  }>
+  /** Token expiration time in seconds (default 30 days) */
+  lifetime: number
+  /** Token refresh time in seconds (default 10 minutes) */
+  refresh: number
+  /** Custom token keys LRU cache configuration */
+  cache: {
+    max: number
+    ttl: number
+  }
+}