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

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

@@ -1,28 +1,91 @@
-import assert from 'node:assert'
+import { it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { generate } from 'randomstring'
 import { timeout } from '@toa.io/generic'
-import { Effect as Encrypt } from './encrypt'
-import { computation as decrypt } from './decrypt'
-import { type Context, type Identity } from './types'
+import { Effect as Encrypt } from './encrypt.js'
+import { Computation as Decrypt } from './decrypt.js'
+import { type Context, type Identity } from './lib/index.js'
+import type { Secret } from '@toa.io/types'
 
 let encrypt: Encrypt
+let decrypt: Decrypt
+
+const context: Context = {
+  remote: { identity: { keys: null } },
+  logs: { debug: () => undefined }
+} as unknown as Context
 
-const context: Context = {} as unknown as Context
 const authority = generate()
 
 beforeEach(() => {
   context.configuration = {
-    key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog',
-    lifetime: 1000,
-    refresh: 2
+    keys: [
+      { id: 'key0', key: secret('sTxL6qVOadKkUJwh3FveU53XgTEo3Sdfg7k2FfiIKfs') },
+      { id: 'legacy0', key: secret('k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog'), format: 'paseto' }
+    ],
+    lifetime: 1,
+    refresh: 2,
+    cache: {
+      max: 1024,
+      ttl: 3
+    }
   }
 
   encrypt = new Encrypt()
   encrypt.mount(context)
+
+  decrypt = new Decrypt()
+  decrypt.mount(context)
+})
+
+it('should use the first encryption key as active and expose its id as kid', async () => {
+  context.configuration.keys.unshift({
+    id: 'legacy-first',
+    key: secret('k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog'),
+    format: 'paseto'
+  })
+  context.configuration.keys.push({
+    id: 'key1',
+    key: secret('5I0iSKw3yfBkQ4AXfA8eR-tWR0Q1dpn4x3bPrPzHkP0')
+  })
+
+  encrypt.mount(context)
+
+  const encrypted = await encrypt.execute({
+    authority,
+    identity: { id: generate(), roles: [] }
+  })
+
+  if (encrypted instanceof Error)
+    throw encrypted
+
+  const header = JSON.parse(Buffer.from(encrypted.split('.')[0], 'base64url').toString())
+
+  assert.partialDeepStrictEqual(header, { kid: 'key0', alg: 'dir', enc: 'A256GCM' })
+})
+
+it('should encrypt with configured lifetime by default', async () => {
+  const identity: Identity = { id: generate(), roles: [] }
+
+  const encrypted = await encrypt.execute({
+    authority,
+    identity
+  })
+
+  if (encrypted instanceof Error)
+    throw encrypted
+
+  await assert.partialDeepStrictEqual(await decrypt.execute(encrypted), { iss: authority, identity })
+
+  await timeout(context.configuration.lifetime * 1000)
+
+  const thrown: any = await decrypt.execute(encrypted)
+        assert.deepStrictEqual(thrown.code, 'INVALID_TOKEN')
 })
 
 it('should encrypt with given lifetime', async () => {
-  const identity: Identity = { id: generate() }
+  const identity: Identity = { id: generate(), roles: [] }
   const lifetime = 0.1
 
   const encrypted = await encrypt.execute({
@@ -31,18 +94,19 @@ it('should encrypt with given lifetime', async () => {
     lifetime
   })
 
-  if (encrypted === undefined)
-    throw new Error('?')
+  if (encrypted instanceof Error)
+    throw encrypted
 
-  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ authority, identity })
+  await assert.partialDeepStrictEqual(await decrypt.execute(encrypted), { iss: authority, identity })
 
   await timeout(lifetime * 1000)
 
-  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ message: 'INVALID_TOKEN' })
+  const thrown: any = await decrypt.execute(encrypted)
+        assert.deepStrictEqual(thrown.code, 'INVALID_TOKEN')
 })
 
 it('should encrypt without lifetime INSECURE', async () => {
-  const identity: Identity = { id: generate() }
+  const identity: Identity = { id: generate(), roles: [] }
   const lifetime = 0
 
   const encrypted = await encrypt.execute({
@@ -51,9 +115,31 @@ it('should encrypt without lifetime INSECURE', async () => {
     lifetime
   })
 
-  const decrypted = await decrypt(encrypted, context)
+  if (encrypted instanceof Error)
+    throw encrypted
+
+  const decrypted = await decrypt.execute(encrypted)
 
   assert.ok(!(decrypted instanceof Error))
 
-  expect(decrypted.identity).toMatchObject(identity)
+  assert.partialDeepStrictEqual(decrypted.identity, identity)
 })
+
+it('should keep the identity permissions when none are given', async () => {
+  const permissions = { '/notes/': ['GET'] }
+  const identity: Identity = { id: generate(), roles: [], permissions }
+
+  const encrypted = await encrypt.execute({ authority, identity, lifetime: 100 })
+
+  if (encrypted instanceof Error)
+    throw encrypted
+
+  const decrypted = await decrypt.execute(encrypted)
+
+  assert.ok(!(decrypted instanceof Error))
+  assert.deepStrictEqual(decrypted.identity.permissions, permissions)
+})
+
+function secret (value: string): Secret {
+  return { unwrap: () => value }
+}

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

@@ -1,29 +1,58 @@
-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, Maybe } from '@toa.io/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
+    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> {
-    const lifetime = input.lifetime === undefined ? this.lifetime : input.lifetime * 1000
+  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 exp = lifetime === 0
-      ? undefined
-      : new Date(Date.now() + lifetime).toISOString()
+    const lifetime = input.lifetime === undefined ? this.lifetime : (input.lifetime * 1000)
 
-    const payload: Partial<Claim> = {
-      identity: input.identity,
-      aud: input.authority,
-      exp
+    const identity: Identity = {
+      id: input.identity.id,
+      roles: input.scopes ?? input.identity.roles
     }
 
-    return await V3.encrypt(payload, this.key)
+    const permissions = input.permissions ?? input.identity.permissions
+
+    if (permissions !== undefined)
+      identity.permissions = permissions
+
+    const key = input.key ?? 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 (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,83 @@
+import { quote } from '@toa.io/generic'
+import type { Maybe, Operation } from '@toa.io/types'
+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
+    this.lifetime = context.configuration.lifetime * 1000
+  }
+
+  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 } = input
+
+    const token = await this.encrypt({
+      input: {
+        authority,
+        identity,
+        lifetime,
+        scopes,
+        permissions,
+        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[]>
+}
+
+interface Output {
+  kid: string
+  exp?: number
+  token: string
+}

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

@@ -0,0 +1,3 @@
+export * from './pad.js'
+export * from './types.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/lib/paseto.test.ts

@@ -0,0 +1,51 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { DecryptFactory, EncryptFactory, ExportKeyFactory, GenerateKeyFactory, ImportKeyFactory }
+  from 'paseto/v3/local'
+
+const generateKey = GenerateKeyFactory().run
+const exportKey = ExportKeyFactory().run
+const importKey = ImportKeyFactory().run
+const encrypt = EncryptFactory().run
+const decrypt = DecryptFactory().run
+
+it('should export a generated key as PASERK', async () => {
+  const paserk = await exportKey(await generateKey({ extractable: true }))
+
+  assert.match(paserk, /^k3\.local\./)
+})
+
+it('should round trip a token', async () => {
+  const key = await importKey(await exportKey(await generateKey({ extractable: true })))
+  const token = await encrypt(key, { iss: 'test', sub: 'me' })
+
+  assert.match(token, /^v3\.local\./)
+
+  const { claims } = await decrypt(key, token, { allowNonExpiring: true })
+
+  assert.partialDeepStrictEqual(claims, { iss: 'test', sub: 'me' })
+})
+
+it('should carry the key id in the footer, which is read without the key', async () => {
+  const key = await importKey(await exportKey(await generateKey({ extractable: true })))
+  const token = await encrypt(key, { iss: 'test' },
+    { footer: new TextEncoder().encode(JSON.stringify({ kid: 'key0' })) })
+
+  // decrypt reads it, and so does anyone holding only the token
+  const [, , , footer] = token.split('.')
+
+  assert.deepStrictEqual(JSON.parse(Buffer.from(footer, 'base64url').toString()), { kid: 'key0' })
+})
+
+it('should decrypt a token issued under paseto 3', async () => {
+  // both written by paseto 3.1.4: the legacy path exists to read tokens already in the wild
+  const key = await importKey('k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog')
+  const token = 'v3.local.Fm7vzrYSDh7Kc9j_2eNr4vwWw5jSEOIKrh_vCbteQQP57tFo5xxk7koNIJQNcH9b' +
+    'O4yH9ItoC-fWL3ycm-YqBIsadjfbSOvwhffP130-tw3MZZ5PNJzFe6afNa4wxbKpa1bWtOwwULJpAqmZ' +
+    '.eyJraWQiOiJsZWdhY3kwIn0'
+
+  const { claims } = await decrypt(key, token, { allowNonExpiring: true })
+
+  assert.partialDeepStrictEqual(claims, { iss: 'legacy', sub: 'old' })
+})

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

@@ -0,0 +1,102 @@
+import type { Call, Maybe, Observation, Secret, telemetry } from '@toa.io/types'
+
+export interface Context {
+  local: {
+    observe: Observation<Entity>
+    encrypt: Call<Maybe<string>, EncryptInput>
+    decrypt: Call<Maybe<DecryptOutput>, string>
+  }
+  remote: {
+    identity: {
+      keys: {
+        observe: Observation<CustomKey>
+        create: Call<Key>
+      }
+      roles: {
+        list: Call<string[]>
+      }
+    }
+  }
+  configuration: Configuration
+  logs: telemetry.Logs
+}
+
+export interface Configuration {
+  readonly keys: ConfiguredKey[]
+  readonly lifetime: number
+  readonly refresh: number
+  readonly cache: {
+    max: number
+    ttl: number
+  }
+}
+
+export interface ConfiguredKey extends Pick<Key, 'id'> {
+  key: Secret
+  format?: 'jwe' | 'paseto'
+}
+
+export interface Entity {
+  revokedAt?: number
+}
+
+export interface Identity extends Record<string, any> {
+  id: string
+  roles: string[]
+  permissions?: Record<string, string[]>
+}
+
+export interface AuthenticateInput {
+  authority: string
+  credentials: string
+}
+
+export interface AuthenticateOutput {
+  identity: Identity
+  refresh: boolean
+}
+
+export interface EncryptInput {
+  authority: string
+  identity: Identity
+  lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  key?: Key
+}
+
+export interface DecryptOutput {
+  iss: string
+  iat: string
+  exp?: string
+  identity: Identity
+  refresh: boolean
+
+  /** encrypted with a key of its own, see `issue` */
+  custom: boolean
+}
+
+export interface Claims {
+  identity: Identity
+  iss: string
+  iat: string
+  exp?: string
+}
+
+export interface JWEClaims {
+  identity: Identity
+  iss: string
+  iat: number
+  exp?: number
+}
+
+export interface Key {
+  id: string
+  key: string
+  label: string
+}
+
+export interface CustomKey extends Key {
+  identity: string
+  revokedAt?: number
+}

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

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