@toa.io/extensions.exposition 1.0.0-alpha.30 → 1.0.0-alpha.301

package/components/identity.passkeys/source/challenge.ts

@@ -0,0 +1,119 @@
+import { randomBytes } from 'node:crypto'
+import { newid, quote } from '@toa.io/generic'
+import { MAX_KEYS } from './lib/const.ts'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context } from './types/index.ts'
+
+export class Effect implements Operation {
+  private timeout!: number
+  private authenticator?: AuthenticatorSelectionCriteria
+  private credParams!: PublicKeyCredentialParameters[]
+  private enumerate!: Context['local']['enumerate']
+  private stash!: Context['stash']
+  private logs!: Context['logs']
+
+  public mount(context: Context): void {
+    this.timeout = context.configuration.timeout
+    this.credParams = context.configuration.algorithms.map((alg) => ({
+      type: 'public-key',
+      alg
+    }))
+
+    if (context.configuration.verification !== undefined) {
+      this.authenticator ??= {}
+      this.authenticator.userVerification = context.configuration.verification
+    }
+
+    if (context.configuration.residence !== undefined) {
+      this.authenticator ??= {}
+      this.authenticator.residentKey = context.configuration.residence
+
+      if (context.configuration.residence === 'required')
+        this.authenticator.requireResidentKey = true
+    }
+
+    this.enumerate = context.local.enumerate
+    this.stash = context.stash
+    this.logs = context.logs
+  }
+
+  public async execute(input: Input): Promise<Output> {
+    const { type, identity, authority } = input
+    const challenge = await this.createChallenge(authority)
+
+    const options: Output = {
+      challenge,
+      timeout: this.timeout
+    }
+
+    if (type === 'creation') options.identity = identity ?? newid()
+
+    const keys =
+      identity === undefined || identity === null
+        ? []
+        : await this.enumerate({
+            query: {
+              criteria: `identity==${quote(identity)}`,
+              projection: ['kid', 'transports'],
+              limit: MAX_KEYS
+            }
+          })
+
+    if (type === 'creation')
+      return {
+        ...options,
+        excludeCredentials: keys.map(({ kid, transports }) => ({ id: kid, transports })),
+        pubKeyCredParams: this.credParams,
+        authenticatorSelection: this.authenticator
+      } satisfies CreationOptions
+    else
+      return {
+        ...options,
+        allowCredentials: keys.map(({ kid, transports }) => ({ id: kid, transports })),
+        userVerification: this.authenticator?.userVerification
+      } satisfies RequestOptions
+  }
+
+  private async createChallenge(authority: string): Promise<string> {
+    const challenge = randomBytes(32).toString('base64url')
+    const key = `challenge:${authority}:${challenge}`
+
+    this.logs.debug('Creating challenge', { key })
+
+    await this.stash.set(key, 1, 'EX', (this.timeout / 1000) * EX_GAP)
+
+    return challenge
+  }
+}
+
+const EX_GAP = 1.5
+
+interface Input {
+  type: 'creation' | 'request'
+  authority: string
+  identity?: string | null
+}
+
+type Output = CreationOptions | RequestOptions
+
+interface CommonOptions {
+  identity?: string
+  challenge: string
+  timeout: number
+}
+
+interface KeyDescriptor {
+  id: string
+  transports?: string[]
+}
+
+type CreationOptions = CommonOptions &
+  Omit<
+    PublicKeyCredentialCreationOptions,
+    'challenge' | 'rp' | 'user' | 'excludeCredentials'
+  > & { excludeCredentials?: KeyDescriptor[] }
+
+type RequestOptions = CommonOptions &
+  Omit<PublicKeyCredentialRequestOptions, 'challenge' | 'allowCredentials'> & {
+    allowCredentials?: KeyDescriptor[]
+  }

package/components/identity.passkeys/source/create.ts

@@ -0,0 +1,83 @@
+import {
+  verifyRegistrationResponse,
+  type RegistrationResponseJSON
+} from '@simplewebauthn/server'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Passkey } from './types/index.ts'
+
+// https://github.com/MasterKale/SimpleWebAuthn/blob/master/packages/server/src/registration/verifyRegistrationResponse.ts#L51
+
+export class Transition implements Operation {
+  private algorithms!: number[]
+  private stash!: Context['stash']
+  private logs!: Context['logs']
+  private verification!: boolean
+  private presence!: boolean
+
+  public mount(context: Context): void {
+    this.algorithms = context.configuration.algorithms
+    this.verification = context.configuration.verification === 'required'
+    this.presence = context.configuration.residence === 'required'
+    this.stash = context.stash
+    this.logs = context.logs
+  }
+
+  public async execute(input: Input, object: Passkey): Promise<Passkey | Error> {
+    const { authority, identity, label, ...response } = input
+
+    // rawId is not sent from the client
+    response.rawId = response.id
+
+    const verified = await verifyRegistrationResponse({
+      response,
+      expectedOrigin: input.origin,
+      expectedChallenge: async (challenge) => this.verifyChallenge(authority, challenge),
+      supportedAlgorithmIDs: this.algorithms,
+      requireUserVerification: this.verification,
+      requireUserPresence: this.presence
+    }).catch((e) => {
+      this.logs.info('Failed to verify registration response', { message: e.message })
+
+      return ERR_FAILED as Error
+    })
+
+    if (verified instanceof Error) return verified
+
+    if (!verified.verified || verified.registrationInfo?.credential === undefined)
+      return ERR_INVALID
+
+    const reg = verified.registrationInfo
+
+    object.authority = authority
+    object.identity = identity
+    object.kid = reg.credential.id
+    object.aid = reg.aaguid
+    object.synced = reg.credentialBackedUp
+    object.key = Buffer.from(reg.credential.publicKey).toString('base64url')
+    object.transports = reg.credential.transports
+    object.label = label
+
+    return object
+  }
+
+  private async verifyChallenge(authority: string, challenge: string): Promise<boolean> {
+    const n = await this.stash.del(`challenge:${authority}:${challenge}`)
+
+    return n === 1
+  }
+}
+
+const ERR_FAILED = new (class FailedError extends Error {
+  public readonly code = 'FAILED'
+})()
+
+const ERR_INVALID = new (class InvalidError extends Error {
+  public readonly code = 'INVALID'
+})()
+
+export interface Input extends RegistrationResponseJSON {
+  authority: string
+  origin: string
+  identity: string
+  label?: string
+}

package/components/identity.passkeys/source/delete.ts

@@ -0,0 +1,19 @@
+import { quote } from '@toa.io/generic'
+import type { Context } from './types/index.ts'
+
+export async function effect(
+  { authority, identity, id }: Input,
+  context: Context
+): Promise<void | null> {
+  return await context.local.terminate({
+    query: {
+      criteria: `authority==${quote(authority)};identity==${quote(identity)};id==${quote(id)}`
+    }
+  })
+}
+
+interface Input {
+  authority: string
+  identity: string
+  id: string
+}

package/components/identity.passkeys/source/lib/const.ts

@@ -0,0 +1 @@
+export const MAX_KEYS = 128

package/components/identity.passkeys/source/list.ts

@@ -0,0 +1,21 @@
+import { quote } from '@toa.io/generic'
+import { MAX_KEYS } from './lib/const.ts'
+import type { Context, Passkey } from './types/index.ts'
+
+export async function computation(
+  { authority, identity }: Input,
+  context: Context
+): Promise<Passkey[]> {
+  return await context.local.enumerate({
+    query: {
+      criteria: `authority==${quote(authority)};identity==${quote(identity)}`,
+      projection: ['aid', 'synced', 'label'],
+      limit: MAX_KEYS
+    }
+  })
+}
+
+interface Input {
+  authority: string
+  identity: string
+}

package/components/identity.passkeys/source/types/Configuration.ts

@@ -0,0 +1,6 @@
+export interface Configuration {
+  algorithms: number[]
+  timeout: number
+  verification?: UserVerificationRequirement
+  residence?: ResidentKeyRequirement
+}

package/components/identity.passkeys/source/types/Context.ts

@@ -0,0 +1,17 @@
+import type { Observation, Transition } from '@toa.io/core/types'
+import type { Stash } from '@toa.io/extensions.stash'
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type { Configuration } from './Configuration.ts'
+import type { Passkey } from './Passkey.ts'
+import type { Input as UseInput, Output as UseOutput } from '../use.ts'
+
+export interface Context {
+  configuration: Configuration
+  stash: Stash
+  logs: Logs
+  local: {
+    enumerate: Observation<Passkey[], never, Passkey>
+    terminate: Transition<void, void, Passkey>
+    use: Transition<UseOutput, UseInput>
+  }
+}

package/components/identity.passkeys/source/types/Passkey.ts

@@ -0,0 +1,12 @@
+export interface Passkey {
+  id: string
+  authority: string
+  identity: string
+  kid: string
+  aid: string
+  synced: boolean
+  key: string
+  counter: number
+  transports?: string[]
+  label?: string
+}

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

@@ -0,0 +1,2 @@
+export type { Context } from './Context.ts'
+export type { Passkey } from './Passkey.ts'

package/components/identity.passkeys/source/use.ts

@@ -0,0 +1,81 @@
+import { verifyAuthenticationResponse } from '@simplewebauthn/server'
+import type {
+  AuthenticationResponseJSON,
+  WebAuthnCredential
+} from '@simplewebauthn/server'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Passkey } from './types/index.ts'
+
+export class Transition implements Operation {
+  private stash!: Context['stash']
+  private logs!: Context['logs']
+  private verification!: boolean
+  private presence!: boolean
+
+  public mount(context: Context): void {
+    this.stash = context.stash
+    this.logs = context.logs
+    this.verification = context.configuration.verification === 'required'
+    this.presence = context.configuration.residence === 'required'
+  }
+
+  public async execute(input: Input, object: Passkey): Promise<Output> {
+    const { origin, ...rest } = input
+    const response: AuthenticationResponseJSON = { ...rest, rawId: input.id }
+    const credential = toCredential(object)
+
+    const verified = await verifyAuthenticationResponse({
+      response,
+      credential,
+      expectedOrigin: origin,
+      expectedRPID: new URL(origin).hostname,
+      expectedChallenge: async (challenge) =>
+        this.verifyChallenge(object.authority, challenge),
+      requireUserVerification: this.verification
+    }).catch((e) => {
+      this.logs.info('Failed to verify authentication response', { message: e.message })
+
+      return ERR_FAILED as Error
+    })
+
+    if (verified instanceof Error) return verified
+
+    if (!verified.verified) return ERR_INVALID
+
+    object.counter = verified.authenticationInfo.newCounter
+
+    return object.identity
+  }
+
+  private async verifyChallenge(authority: string, challenge: string): Promise<boolean> {
+    const key = `challenge:${authority}:${challenge}`
+    const n = await this.stash.del(`challenge:${authority}:${challenge}`)
+
+    this.logs.debug(n === 1 ? 'Challenge verified' : 'Challenge not found', { key, n })
+
+    return n === 1
+  }
+}
+
+function toCredential(passkey: Passkey): WebAuthnCredential {
+  return {
+    id: passkey.id,
+    publicKey: new Uint8Array(Buffer.from(passkey.key, 'base64url')),
+    counter: passkey.counter,
+    transports: passkey.transports
+  }
+}
+
+const ERR_FAILED = new (class FailedError extends Error {
+  public readonly code = 'FAILED'
+})()
+
+const ERR_INVALID = new (class InvalidError extends Error {
+  public readonly code = 'INVALID'
+})()
+
+export interface Input extends Omit<AuthenticationResponseJSON, 'rawId'> {
+  origin: string
+}
+
+export type Output = string | Error

package/components/identity.passkeys/tsconfig.json

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

package/components/identity.passkeys/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.passkeys/types/toa.d.ts

@@ -0,0 +1,121 @@
+// 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 { FetchInit } from '@toa.io/extensions.fetch'
+import type { Stash } from '@toa.io/extensions.stash'
+import type { Logs, Span } from '@toa.io/extensions.telemetry'
+import type { Readable } from 'node:stream'
+
+export interface Entity {
+  authority: string
+  identity: string
+  kid: string
+  /** AAGUID */
+  aid: string
+  /** credentialBackedUp */
+  synced: boolean
+  /** Base64-encoded Uint8Array */
+  key: string
+  counter: number
+  transports?: string[]
+  label?: string
+  id: string
+  VERSION: number
+  CREATED: number
+  UPDATED: number
+  DELETED: number | null
+  REGION: number
+}
+
+export type ChallengeInput = {
+  type: "creation" | "request"
+  authority: string
+  identity?: string
+}
+
+export type CreateInput = {
+  authority: string
+  origin: string
+  identity: string
+  label: string
+  id: string
+  type: string
+  response: {
+    id?: string
+    response?: {
+      attestationObject: string
+      clientDataJSON: string
+      transports: string[]
+      publicKeyAlgorithm: number
+      publicKey: string
+      authenticatorData: string
+    }
+  }
+  authenticatorAttachment?: string | null
+  clientExtensionResults?: Record<string, unknown>
+}
+
+export type UseInput = {
+  origin: string
+  id: string
+  type?: string
+  response: {
+    authenticatorData?: string
+    clientDataJSON?: string
+    signature?: string
+    userHandle?: string
+  }
+  authenticatorAttachment?: string
+  clientExtensionResults?: Record<string, unknown>
+}
+
+export type AuthenticateInput = {
+  authority: string
+  origin: string
+  id: string
+  type?: string
+  response: {
+    authenticatorData?: string
+    clientDataJSON?: string
+    signature?: string
+    userHandle?: string
+  }
+  authenticatorAttachment?: string
+  clientExtensionResults?: Record<string, unknown>
+}
+
+export type ListInput = {
+  authority: string
+  identity: string
+}
+
+export type DeleteInput = {
+  authority: string
+  identity: string
+  id: string
+}
+
+export interface Component {
+  challenge: (request: { input: ChallengeInput, task?: boolean }, options?: Options) => Promise<unknown>
+  create: (request: { input: CreateInput, task?: boolean }, options?: Options) => Promise<unknown | RemoteError<"FAILED" | "INVALID">>
+  use: (request: { input: UseInput, query: Query<Entity>, task?: boolean }, options?: Options) => Promise<unknown | RemoteError<"FAILED" | "INVALID">>
+  authenticate: (request: { input: AuthenticateInput, task?: boolean }, options?: Options) => Promise<unknown | RemoteError<"MISS" | "FAILED" | "INVALID">>
+  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 {
+  algorithms?: number[]
+  timeout?: number
+  /** AuthenticatorSelectionCriteria.userVerification */
+  verification?: "required" | "preferred" | "discouraged"
+  /** AuthenticatorSelectionCriteria.residentKey */
+  residence?: "required" | "preferred" | "discouraged"
+}

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

@@ -2,27 +2,52 @@ namespace: identity
 name: roles
 
 entity:
-  schema:
-    identity*: string
-    role*: /^[a-zA-Z0-9]{1,32}(:[a-zA-Z0-9]{1,32}){0,8}$/
-    grantor: string
-  unique:
-    role: [identity, role]
+  properties:
+    grantor:
+      type: string
+    identity: &identity
+      type: string
+      pattern: '[a-z0-9]{32}'
+    role: &role
+      type: string
+      pattern: ^[a-zA-Z0-9]{0,32}(:[a-zA-Z0-9]{0,32}){0,8}$
+  required:
+    - identity
+    - role
 
 operations:
   grant:
     query: false
     input:
-      identity*: .
-      role*: .
-      grantor:
-        id: string
-        roles: [string]
+      properties:
+        grantor:
+          properties:
+            id:
+              type: string
+            roles:
+              type: array
+              items:
+                type: string
+          type: object
+        identity: *identity
+        role: *role
+      type: object
+      required:
+        - identity
+        - role
+    errors:
+      - INACCESSIBLE_SCOPE
   list:
-    output: [string]
+    output:
+      type: array
+      items:
+        type: string
   principal:
     input:
-      id: string
+      properties:
+        id:
+          type: string
+      type: object
 
 receivers:
   identity.basic.principal: principal
@@ -42,3 +67,7 @@ exposition:
       io:output: true # array of strings
       auth:id: identity
       endpoint: list
+    /:role:
+      DELETE:
+        io:output: false
+        endpoint: terminate

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

@@ -0,0 +1,8 @@
+- index:
+    name: unique_role
+    keys:
+      identity: asc
+      role: asc
+    unique: true
+    partial:
+      DELETED: null

package/components/identity.roles/operations/grant.js

@@ -1,21 +1,21 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.transition = void 0;
-const error_value_1 = require("error-value");
-async function transition(input, object) {
+export async function transition(input, object) {
     if (input.grantor === undefined)
         return Object.assign(object, input);
-    if (!within('system:identity:roles', input.grantor.roles) &&
-        !within(input.role, input.grantor.roles))
-        return ERR_OUT_OF_SCOPE;
+    // a manager grants any role; a delegate grants within its own scopes, and never the
+    // right to grant
+    if (!within(MANAGEMENT, input.grantor.roles) &&
+        (!within(input.role, input.grantor.roles) || within(input.role, [MANAGEMENT])))
+        return ERR_INACCESSIBLE_SCOPE;
     object.role = input.role;
     object.identity = input.identity;
     object.grantor = input.grantor.id;
     return object;
 }
-exports.transition = transition;
 function within(role, scopes) {
     return scopes.some((scope) => role === scope || role.startsWith(scope + ':'));
 }
-const ERR_OUT_OF_SCOPE = (0, error_value_1.Err)('OUT_OF_SCOPE');
-//# sourceMappingURL=grant.js.map
+const MANAGEMENT = 'system:identity:roles';
+const ERR_INACCESSIBLE_SCOPE = new (class InaccessibleScopeError extends Error {
+    code = 'INACCESSIBLE_SCOPE';
+})();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ3JhbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zb3VyY2UvZ3JhbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBRUEsTUFBTSxDQUFDLEtBQUssVUFBVSxVQUFVLENBQUMsS0FBWSxFQUFFLE1BQWM7SUFDM0QsSUFBSSxLQUFLLENBQUMsT0FBTyxLQUFLLFNBQVM7UUFBRSxPQUFPLE1BQU0sQ0FBQyxNQUFNLENBQUMsTUFBTSxFQUFFLEtBQUssQ0FBQyxDQUFBO0lBRXBFLG9GQUFvRjtJQUNwRixpQkFBaUI7SUFDakIsSUFDRSxDQUFDLE1BQU0sQ0FBQyxVQUFVLEVBQUUsS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUM7UUFDeEMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsSUFBSSxFQUFFLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLElBQUksTUFBTSxDQUFDLEtBQUssQ0FBQyxJQUFJLEVBQUUsQ0FBQyxVQUFVLENBQUMsQ0FBQyxDQUFDO1FBRTlFLE9BQU8sc0JBQXNCLENBQUE7SUFFL0IsTUFBTSxDQUFDLElBQUksR0FBRyxLQUFLLENBQUMsSUFBSSxDQUFBO0lBQ3hCLE1BQU0sQ0FBQyxRQUFRLEdBQUcsS0FBSyxDQUFDLFFBQVEsQ0FBQTtJQUNoQyxNQUFNLENBQUMsT0FBTyxHQUFHLEtBQUssQ0FBQyxPQUFPLENBQUMsRUFBRSxDQUFBO0lBRWpDLE9BQU8sTUFBTSxDQUFBO0FBQ2YsQ0FBQztBQUVELFNBQVMsTUFBTSxDQUFDLElBQVksRUFBRSxNQUFnQjtJQUM1QyxPQUFPLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLElBQUksS0FBSyxLQUFLLElBQUksSUFBSSxDQUFDLFVBQVUsQ0FBQyxLQUFLLEdBQUcsR0FBRyxDQUFDLENBQUMsQ0FBQTtBQUMvRSxDQUFDO0FBRUQsTUFBTSxVQUFVLEdBQUcsdUJBQXVCLENBQUE7QUFFMUMsTUFBTSxzQkFBc0IsR0FBRyxJQUFJLENBQUMsTUFBTSxzQkFBdUIsU0FBUSxLQUFLO0lBQzVELElBQUksR0FBRyxvQkFBb0IsQ0FBQTtDQUM1QyxDQUFDLEVBQUUsQ0FBQSJ9

package/components/identity.roles/operations/lib/Entity.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=Entity.js.map
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiRW50aXR5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc291cmNlL2xpYi9FbnRpdHkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/components/identity.roles/operations/list.js

@@ -1,8 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.observation = void 0;
-function observation(_, objects) {
+export function observation(_, objects) {
     return objects.map(({ role }) => role);
 }
-exports.observation = observation;
-//# sourceMappingURL=list.js.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGlzdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9saXN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE1BQU0sVUFBVSxXQUFXLENBQUMsQ0FBVSxFQUFFLE9BQWlCO0lBQ3ZELE9BQU8sT0FBTyxDQUFDLEdBQUcsQ0FBQyxDQUFDLEVBQUUsSUFBSSxFQUFFLEVBQUUsRUFBRSxDQUFDLElBQUksQ0FBQyxDQUFBO0FBQ3hDLENBQUMifQ==