@toa.io/extensions.exposition 1.0.0-alpha.101 → 1.0.0-alpha.102

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

@@ -2,27 +2,52 @@ import assert from 'node:assert'
 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 { Computation as Decrypt } from './decrypt'
+import { type Context, type Identity } from './lib'
 
 let encrypt: Encrypt
+let decrypt: Decrypt
 
-const context: Context = {} as unknown as Context
+const context: Context = { remote: { identity: { keys: null } } } as unknown as Context
 const authority = generate()
 
 beforeEach(() => {
   context.configuration = {
-    key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog',
-    lifetime: 1000,
-    refresh: 2
+    keys: {
+      key0: 'k3.local.m28p8SrbS467t-2IUjQuSOqmjvi24TbXhyjAW_dOrog'
+    },
+    lifetime: 1,
+    refresh: 2,
+    cache: 3
   }
 
   encrypt = new Encrypt()
   encrypt.mount(context)
+
+  decrypt = new Decrypt()
+  decrypt.mount(context)
+})
+
+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 expect(decrypt.execute(encrypted)).resolves.toMatchObject({ iss: authority, identity })
+
+  await timeout(context.configuration.lifetime * 1000)
+
+  await expect(decrypt.execute(encrypted)).resolves.toMatchObject({ 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 +56,18 @@ 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 expect(decrypt.execute(encrypted)).resolves.toMatchObject({ iss: authority, identity })
 
   await timeout(lifetime * 1000)
 
-  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ message: 'INVALID_TOKEN' })
+  await expect(decrypt.execute(encrypted)).resolves.toMatchObject({ 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,7 +76,10 @@ 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))
 

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

@@ -1,29 +1,53 @@
 import { V3 } from 'paseto'
-import { type Operation } from '@toa.io/types'
-import { type Claim, type Context, type EncryptInput } from './types'
+import { Err } from 'error-value'
+import type { Operation, Maybe } from '@toa.io/types'
+import type { Identity, Claims, Context, EncryptInput, Key } from './lib'
 
 export class Effect implements Operation {
-  private key: string = ''
+  private key!: Key
   private lifetime: number = 0
 
   public mount (context: Context): void {
-    this.key = context.configuration.key0
+    const [id, secret] = Object.entries(context.configuration.keys)[0]
+
+    this.key = { id, key: secret }
     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>> {
+    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 payload: Partial<Claim> = {
-      identity: input.identity,
-      aud: input.authority,
-      exp
+    const identity: Identity = {
+      id: input.identity.id,
+      roles: input.scopes ?? input.identity.roles
+    }
+
+    if (input.permissions !== undefined)
+      identity.permissions = input.permissions
+
+    const payload: Partial<Claims> = {
+      identity,
+      iss: input.authority
     }
 
-    return await V3.encrypt(payload, this.key)
+    if (exp !== undefined)
+      payload.exp = exp
+
+    const key = input.key ?? this.key
+
+    return await V3.encrypt(payload, key.key, { footer: { kid: key.id } })
   }
 }
+
+function within (scope: string, roles: string[]): boolean {
+  return roles.some((role) => role === scope || scope.startsWith(role + ':'))
+}
+
+const ERR_INACCESSIBLE_SCOPE = new Err('INACCESSIBLE_SCOPE')

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

@@ -0,0 +1,57 @@
+import type { Maybe, Operation } from '@toa.io/types'
+import type { Context, Identity } from './lib'
+
+export class Effect implements Operation {
+  private keys!: Context['remote']['identity']['keys']
+  private roles!: Context['remote']['identity']['roles']
+  private encrypt!: Context['local']['encrypt']
+
+  public mount (context: Context): void {
+    this.keys = context.remote.identity.keys
+    this.roles = context.remote.identity.roles
+    this.encrypt = context.local.encrypt
+  }
+
+  public async execute (input: Input): Promise<Maybe<string>> {
+    const key = await this.keys.create({
+      input: {
+        identity: input.identity,
+        name: input.name
+      }
+    })
+
+    const roles = await this.roles.list({
+      query: {
+        criteria: `identity==${input.identity}`,
+        limit: 1024
+      }
+    })
+
+    const identity: Identity = {
+      id: input.identity,
+      roles
+    }
+
+    const { authority, lifetime, scopes, permissions } = input
+
+    return await this.encrypt({
+      input: {
+        authority,
+        identity,
+        lifetime,
+        scopes,
+        permissions,
+        key
+      }
+    })
+  }
+}
+
+interface Input {
+  authority: string
+  identity: string
+  lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  name?: string
+}

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

@@ -0,0 +1,2 @@
+export * from './pad'
+export * from './types'

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,16 @@
+import { V3 } from 'paseto'
+
+it('should be ok', async () => {
+  const payload = { iss: 'test', sub: 'me' }
+  const key = await V3.generateKey('local', { format: 'paserk' })
+  const token = await V3.encrypt(payload, key, { footer: 'key0' })
+  const [, , , footer] = token.split('.')
+  const kid = Buffer.from(footer, 'base64url').toString('utf-8')
+
+  console.log(footer, kid)
+  console.log(key)
+
+  const decrypted = await V3.decrypt(token, key)
+
+  console.log(decrypted)
+})

package/components/identity.tokens/source/{types.ts → lib/types.ts}

@@ -1,18 +1,30 @@
-import { type Call, type Maybe, type Observation } from '@toa.io/types'
+import type { Call, Maybe, Observation } 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
 }
 
 export interface Configuration {
-  readonly key0: string
-  readonly key1?: string
+  readonly keys: Record<string, string>
   readonly lifetime: number
   readonly refresh: number
+  readonly cache: number
 }
 
 export interface Entity {
@@ -21,6 +33,8 @@ export interface Entity {
 
 export interface Identity extends Record<string, any> {
   id: string
+  roles: string[]
+  permissions?: Record<string, string[]>
 }
 
 export interface AuthenticateInput {
@@ -37,19 +51,31 @@ export interface EncryptInput {
   authority: string
   identity: Identity
   lifetime?: number
+  scopes?: string[]
+  permissions?: Record<string, string[]>
+  key?: Key
 }
 
 export interface DecryptOutput {
-  authority: string
-  identity: Identity
+  iss: string
   iat: string
   exp?: string
+  identity: Identity
   refresh: boolean
 }
 
-export interface Claim {
+export interface Claims {
   identity: Identity
-  aud: string
+  iss: string
   iat: string
   exp?: string
 }
+
+export interface Key {
+  id: string
+  key: string
+}
+
+export interface CustomKey extends Key {
+  identity: string
+}

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

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

package/components/octets.storage/operations/put.js

@@ -119,10 +119,10 @@ function toURL (location) {
   }
 }
 
-const ERR_UNTRUSTED = Err('LOCATION_UNTRUSTED', 'Location is not trusted')
-const ERR_LENGTH = Err('LOCATION_LENGTH', 'Content-Length must be 0 when Content-Location is used')
-const ERR_UNAVAILABLE = Err('LOCATION_UNAVAILABLE', 'Location is not available')
-const ERR_INVALID_ID = Err('INVALID_ID', 'Invalid Content-ID')
+const ERR_UNTRUSTED = new Err('LOCATION_UNTRUSTED', 'Location is not trusted')
+const ERR_LENGTH = new Err('LOCATION_LENGTH', 'Content-Length must be 0 when Content-Location is used')
+const ERR_UNAVAILABLE = new Err('LOCATION_UNAVAILABLE', 'Location is not available')
+const ERR_INVALID_ID = new Err('INVALID_ID', 'Invalid Content-ID')
 
 const ID_RX = /^[a-zA-Z0-9-_]{1,32}$/
 

package/documentation/components.md

@@ -122,9 +122,9 @@ configuration:
             k1: <secret-to-be-used-for-hs256>
 ```
 
-## Stateless tokens
+## Local tokens
 
-The `identity.tokens` component manages stateless authentication tokens.
+The `identity.tokens` component manages local authentication tokens.
 
 These tokens carry the information required to authenticate the Identity and authorize access.
 
@@ -143,21 +143,84 @@ authorization: Token ...
 cache-control: no-store
 ```
 
+### Custom tokens
+
+Custom tokens can be issued with a specific set of permissions and scopes for the own Identity or by
+an Identity with the `system:identity:tokens` role.
+
+Tokens are issued with custom secret keys and are not subject to [token rotation](#token-rotation).
+To invalidate a custom token, its secret key must be deleted.
+
+Custom tokens have no `refresh` period, that is, never become obsolete and never refreshed.
+
+```
+POST /identity/tokens/<identity>/
+host: nex.toa.io
+authorization: ...
+accept: application/yaml
+content-type: application/yaml
+
+lifetime: 3600
+scopes: [app:developer]
+permissions:
+  /users/fc8e66dd/: [GET, PUT]
+  /posts/fc8e66dd/**/comments/: [*]
+```
+
+```
+201 Created
+content-type: application/yaml
+
+token: <token>
+```
+
+- `lifetime`: Issued token will be valid for this period
+  (default is specified in [the configuration](#token-rotation)).
+  The value of `0` means the token will not expire, which is supported, but
+  **strongly not recommended** for production environments.
+- `scopes`: Issued token will assume only specified [role scopes](access.md#roles).
+- `permissions`: Issued token will have permissions to access only specified resources and methods.
+  Supports [glob patterns](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)
+  and a wildcard method.
+
+> `roles` and `permissions` are additional restrictions applied on top of the Identity’s inherent
+> privileges.
+
+### Custom token invalidation
+
+Custom tokens can be invalidated by deleting the secret key used to issue them.
+This can be done by the Identity that issued the token or by an Identity with
+the `system:identity:keys` role.
+
+```
+DELETE /identity/keys/<identity>/<key.id>/
+authorization: ...
+```
+
+Token secret key `id` can be obtained from the list of issued tokens (or from the footer of the
+token itself).
+
+```
+GET /identity/keys/<identity>/
+authorization: ...
+```
+
 ### Token encryption
 
 Issued tokens are encrypted
 with [PASETO V3 encryption](https://github.com/panva/paseto/blob/main/docs/README.md#v3encryptpayload-key-options)
-using the `key0` configuration value as a secret.
+using the first key from the `keys` configuration value.
 
 ```yaml
 # context.toa.yaml
 
 configuration:
   identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY
+    keys:
+      2024q1: $TOKEN_SECRET_2024Q1
 ```
 
-The `key0` configuration value is required.
+At least one key in the `keys` configuration value is required.
 
 > Valid secret key may be generated using the [`toa key` command](/runtime/cli/readme.md#key).
 
@@ -197,43 +260,18 @@ Token revocation takes effect once the `refresh` period of the currently issued
 
 ### Secret rotation
 
-Tokens are always encrypted using the `key0` configuration value, and they will be decrypted by
-attempting both
-the `key0` and `key1` values in order.
-
-`key0` is considered the "current key," and `key1` is considered the "previous key."
-
-```yaml
-# context.toa.yaml
-
-configuration:
-  identity.tokens:
-    key0: $TOKEN_ENCRYPTION_KEY_2023Q3
-    key1: $TOKEN_ENCRYPTION_KEY_2023Q2
-```
-
-Secret rotation is performed by adding a new key as the `key0` value and moving the existing `key0`
-to the `key1` value.
-
-When rolling out the new secret key, there will be a period of time when the new key is deployed to
-some Exposition
-instances. During this time, these instances will start using the new key to encrypt tokens, while
-other instances will
-continue using the current key and will not be able to decrypt tokens encrypted with the new key.
-
-To address this issue, the `key1` configuration value may be used as a "transient key."
+Tokens are always encrypted using the first key from the `keys` configuration value,
+and decrypted by the key used to encrypt them.
 
-The secret rotation is a 2-step process:
+To rotate the secret key, a new key must be added to the top of the `keys` configuration value, that
+is, it will be used to encrypt new tokens.
 
-> The process **must not** be performed earlier than the `lifetime` period since the last rotation,
-> as it may invalidate
-> tokens before they expire. Therefore, it is guaranteed that there are no valid tokens issued with
-> the current `key1`
-> value.
+Old keys must be removed only after the `refresh` period of the previously issued tokens has
+expired.
 
-1. Deploy the new secret key to all Exposition instances as `key1`. This enables all instances to
-   decrypt tokens
-   encrypted with the new key while still using the current key for encryption.
+> Let's say you are adding a new secret key each quarter: `2024Q1`, `2024Q2` and so on.
+> The old key `2024Q1` must be removed from the configuration only when the `refresh` period after
+> the new key `2024Q2` was added has expired.
 
 ```yaml
 # context.toa.yaml

package/features/identity.tokens.feature

@@ -127,46 +127,3 @@ Feature: Tokens lifecycle
       """
       401 Unauthorized
       """
-
-  Scenario: Issuing own token
-    Given the `identity.basic` database contains:
-      | _id                              | authority | username  | password                                                     |
-      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-    When the following request is received:
-      """
-      GET /identity/ HTTP/1.1
-      host: nex.toa.io
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      authorization: Token ${{ token }}
-      """
-    When the following request is received:
-      """
-      POST /identity/tokens/ HTTP/1.1
-      host: nex.toa.io
-      authorization: Token ${{ token }}
-      content-type: application/yaml
-
-      lifetime: 0
-      """
-    Then the following reply is sent:
-      """
-      201 Created
-      """
-    # Token scheme must be used
-    When the following request is received:
-      """
-      POST /identity/tokens/ HTTP/1.1
-      host: nex.toa.io
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      content-type: application/yaml
-
-      lifetime: 60
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """