@toa.io/extensions.exposition 0.24.0-alpha.9 → 1.0.0-alpha.10

package/components/identity.federation/source/lib/jwt.ts

@@ -0,0 +1,171 @@
+import crypto from 'node:crypto'
+import * as assert from 'node:assert'
+import { type JwtHeader, type IdToken } from '../types'
+import { type TrustConfiguration } from '../schemas'
+
+export function decodeJwt (token: string): {
+  header: unknown
+  payload: unknown
+  rawHeader: string
+  rawPayload: string
+  signature: string
+} {
+  const [rawHeader, rawPayload, signature] = token.split('.', 3)
+
+  const header = JSON.parse(Buffer.from(rawHeader, 'base64url').toString())
+  const payload = JSON.parse(Buffer.from(rawPayload, 'base64url').toString())
+
+  return { header, payload, rawHeader, rawPayload, signature }
+}
+
+export function validateJwtHeader (header: unknown): asserts header is JwtHeader {
+  assert.ok(header !== null && typeof header === 'object', 'Header is not an object')
+  assert.ok('alg' in header, 'Header is missing alg')
+  assert.ok(typeof header.alg === 'string', 'Header alg is not a string')
+  assert.match(header.alg, /^RS256|HS\d{3}$/, `Unknown algorithm ${header.alg}`)
+  assert.ok(!('kid' in header) || typeof header.kid === 'string', 'kid must be a string if present')
+}
+
+export function validateJwtPayload (payload: unknown,
+  trusted: TrustConfiguration[] = [],
+  header: JwtHeader): asserts payload is IdToken {
+  assert.ok(trusted.length > 0, 'No trusted issuers provided')
+
+  // full list of validations is
+  // at https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
+  assert.ok(payload !== null && typeof payload === 'object', 'Payload is not an object')
+
+  assert.ok('iss' in payload, 'Payload is missing iss')
+  assert.ok(typeof payload.iss === 'string', 'Payload iss is not a string')
+  assert.ok('aud' in payload, 'Payload is missing aud')
+  assert.ok(typeof payload.aud === 'string', 'Payload aud is not a string')
+
+  const issuer = trusted.find((config) => config.issuer === payload.iss)
+
+  assert.ok(issuer !== undefined &&
+      (issuer.audience === undefined || issuer.audience.some((a) => a === payload.aud),
+      `Unknown issuer / audience: ${payload.iss} / ${payload.aud}`))
+
+  if (header.alg.startsWith('HS')) {
+    const secrets = issuer.secrets
+
+    assert.ok(secrets, `We don't have known secrets for ${payload.iss}`)
+
+    const keys = secrets[header.alg]
+
+    assert.ok(keys, `No known secrets for ${header.alg}`)
+
+    if (typeof header.kid === 'string')
+      assert.ok(header.kid in keys, `No secret ${header.kid} provided for ${header.alg}`)
+  }
+
+  assert.ok('sub' in payload, 'Payload is missing sub')
+  assert.ok(typeof payload.sub === 'string', 'Payload sub is not a string')
+
+  assert.ok('exp' in payload, 'Payload is missing exp')
+  assert.ok(typeof payload.exp === 'number', 'Payload exp is not a number')
+  assert.ok(Date.now() < payload.exp * 1000, 'Token is expired')
+
+  assert.ok('iat' in payload, 'Payload is missing iat')
+  assert.ok(typeof payload.iat === 'number', 'Payload iat is not a number')
+  assert.ok(Date.now() >= payload.iat * 1000, 'Token was issued in the future')
+  assert.ok(payload.exp >= payload.iat, 'Payload exp is before iat')
+
+  if ('nbf' in payload) {
+    assert.ok(typeof payload.nbf === 'number', 'Payload nbf is not a number')
+    assert.ok(Date.now() >= payload.nbf * 1000, 'Token is not valid yet')
+  }
+}
+
+export async function validateSignature ({
+  header: { kid, alg },
+  payload: { iss },
+  rawHeader,
+  rawPayload,
+  signature,
+  trusted = []
+}: {
+  readonly header: JwtHeader
+  rawHeader: string
+  readonly payload: IdToken
+  rawPayload: string
+  signature: string
+  trusted?: TrustConfiguration[]
+}): Promise<void> {
+  if (alg.startsWith('HS')) {
+    // symmetric algorithm, issuer is validated at this point
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- `kid` is validated
+    const secrets = trusted.find((c) => c.issuer === iss)!.secrets![alg]
+    const secret = kid !== undefined ? secrets[kid] : Object.values(secrets)[0]
+    const algorithm = alg.replace(/^HS(\d{3})$/, 'sha$1') // HS256 -> sha256
+    const hmac = crypto.createHmac(algorithm, secret)
+
+    hmac.update(rawHeader)
+    hmac.update('.')
+    hmac.update(rawPayload)
+    assert.strictEqual(signature, hmac.digest('base64url'), 'Signature does not match')
+
+    return
+  }
+
+  // Getting issuer public keys
+  const oidcRequest = await fetch(`${iss}/.well-known/openid-configuration`, {
+    cache: 'default'
+  })
+
+  assert.ok(oidcRequest.ok,
+    `Failed to fetch OpenID configuration: ${oidcRequest.statusText}`)
+
+  const { jwks_uri: jwksUri } = (await oidcRequest.json()) as { jwks_uri: string }
+
+  const jwkRequest = await fetch(jwksUri, { cache: 'default' })
+
+  assert.ok(jwkRequest.ok, `Failed to fetch issuer keys: ${jwkRequest.statusText}`)
+
+  const { keys } = (await jwkRequest.json()) as {
+    keys: Array<{ use: string, kid?: string, alg?: string } & crypto.JsonWebKey>
+  }
+
+  // getting corresponding signing key
+  const signingKeys = keys.filter((k) => k.use === 'sig' && k.alg === alg)
+
+  assert.ok(signingKeys.length > 0, 'No acceptable signing keys found')
+
+  assert.ok(kid === undefined || signingKeys.length === 1,
+    'Signing key selection is not deterministic')
+
+  const signingKey = kid === undefined ? signingKeys.find((k) => k.kid === kid) : keys[0]
+
+  assert.ok(signingKey, 'Signing key was not found in issuer keys')
+
+  const verifyFunction = crypto.createVerify('RSA-SHA256')
+
+  verifyFunction.write(rawHeader)
+  verifyFunction.write('.')
+  verifyFunction.write(rawPayload)
+  verifyFunction.end()
+
+  const signatureValid = verifyFunction.verify({ format: 'jwk', key: signingKey },
+    signature,
+    'base64url')
+
+  assert.ok(signatureValid, 'Failed to validate signature')
+}
+
+export async function validateIdToken (token: string,
+  trusted?: TrustConfiguration[]): Promise<IdToken> {
+  const { header, payload, rawHeader, rawPayload, signature } = decodeJwt(token)
+
+  validateJwtHeader(header)
+  validateJwtPayload(payload, trusted, header)
+  await validateSignature({
+    header,
+    rawHeader,
+    payload,
+    rawPayload,
+    signature,
+    trusted
+  })
+
+  return payload
+}

package/components/identity.federation/source/schemas.ts

@@ -0,0 +1,61 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+export interface Schemas {
+  configuration?: {
+    trust?: TrustConfiguration[];
+    /**
+     * Force identities to be explicitly created or incept before being used in authentication
+     */
+    explicit_identity_creation?: boolean;
+    /**
+     * The value of `sub` of an identity token that will be assigned the `system` Role
+     */
+    principal?: {
+      iss: string;
+      sub: string;
+    };
+  };
+  entity?: {
+    /**
+     * 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;
+  };
+}
+export interface TrustConfiguration {
+  /**
+   * Allowed origins for a token `iss` field
+   */
+  issuer: string;
+  /**
+   * Acceptable `aud` value(s)
+   *
+   * @minItems 1
+   */
+  audience?: [string, ...string[]];
+  /**
+   * Symmetric encryption secrets
+   */
+  secrets?: {
+    /**
+     * This interface was referenced by `undefined`'s JSON-Schema definition
+     * via the `patternProperty` "^HS\d{3}$".
+     */
+    [k: string]: {
+      /**
+       * This interface was referenced by `undefined`'s JSON-Schema definition
+       * via the `patternProperty` "^\w+$".
+       */
+      [k: string]: string;
+    };
+  };
+}

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

@@ -0,0 +1,56 @@
+import { type Call, type Observation, type Query } from '@toa.io/types'
+import type { Schemas } from './schemas'
+
+export interface Context {
+  local: {
+    observe: Observation<Entity & { id: string }>
+    transit: Call<TransitOutput, TransitInput>
+  }
+  remote: {
+    identity: {
+      tokens: {
+        revoke: Call<void, IdentityTokensRevokeInput>
+      }
+    }
+  }
+  configuration: Required<Schemas>['configuration']
+}
+
+export type Entity = Required<Schemas>['entity']
+
+export interface TransitInput {
+  readonly iss: string
+  readonly sub: string
+}
+
+export interface TransitOutput {
+  id: string
+}
+
+interface IdentityTokensRevokeInput {
+  query: Query
+}
+
+export interface JwtHeader {
+  typ?: string
+  alg: string
+  kid?: string
+}
+
+/**
+ * @see {@link https://openid.net/specs/openid-connect-core-1_0.html#IDToken}
+ */
+export interface IdToken {
+  iss: string
+  sub: string
+  aud: string
+  exp: number
+  iat: number
+  nbf?: number
+}
+
+export interface AuthenticateOutput {
+  identity: {
+    id: string
+  }
+}

package/components/identity.federation/tsconfig.json

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

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

@@ -4,14 +4,20 @@ name: roles
 entity:
   schema:
     identity*: string
-    role*: string
+    role*: /^[a-zA-Z0-9]{1,16}(:[a-zA-Z0-9]{1,16}){0,8}$/
+    delegator: string
+  unique:
+    unique: [identity, role]
 
 operations:
-  transit:
+  grant:
     query: false
     input:
-      identity*: string
-      role*: string
+      identity*: .
+      role*: .
+      delegator:
+        id: string
+        roles: [string]
   list:
     output: [string]
   principal:
@@ -25,7 +31,13 @@ exposition:
   isolated: true
   /:identity:
     auth:role: system:identity:roles
-    POST: transit
+    auth:rule:
+      delegate: delegator
+      role: system:identity:roles:delegation
+    POST:
+      io:output: [id]
+      endpoint: grant
     GET:
+      io:output: true # array of strings
       auth:id: identity
       endpoint: list

package/components/identity.roles/operations/grant.d.ts

@@ -0,0 +1,10 @@
+import type { Entity } from './lib/Entity';
+export declare function transition(input: Input, object: Entity): Promise<Entity | Error>;
+export interface Input {
+    identity: string;
+    role: string;
+    delegator?: {
+        id: string;
+        roles: string[];
+    };
+}

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

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transition = void 0;
+const error_value_1 = require("error-value");
+async function transition(input, object) {
+    if (input.delegator === undefined)
+        return Object.assign(object, input);
+    if (!allowed(input.role, input.delegator.roles))
+        return ERR_OUT_OF_SCOPE;
+    object.role = input.role;
+    object.identity = input.identity;
+    object.delegator = input.delegator.id;
+    return object;
+}
+exports.transition = transition;
+function allowed(scope, roles) {
+    return roles.some((role) => scope.startsWith(role));
+}
+const ERR_OUT_OF_SCOPE = (0, error_value_1.Err)('OUT_OF_SCOPE');
+//# sourceMappingURL=grant.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grant.js","sourceRoot":"","sources":["../source/grant.ts"],"names":[],"mappings":";;;AAAA,6CAAiC;AAG1B,KAAK,UAAU,UAAU,CAAE,KAAY,EAAE,MAAc;IAC5D,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAC/B,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAErC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC;QAC7C,OAAO,gBAAgB,CAAA;IAEzB,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;IACxB,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IAChC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,CAAA;IAErC,OAAO,MAAM,CAAA;AACf,CAAC;AAZD,gCAYC;AAED,SAAS,OAAO,CAAE,KAAa,EAAE,KAAe;IAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAA;AACrD,CAAC;AAED,MAAM,gBAAgB,GAAG,IAAA,iBAAG,EAAC,cAAc,CAAC,CAAA"}

package/components/identity.roles/operations/lib/Entity.d.ts

@@ -0,0 +1,5 @@
+export interface Entity {
+    identity: string;
+    role: string;
+    delegator?: string;
+}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Entity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Entity.js","sourceRoot":"","sources":["../../source/lib/Entity.ts"],"names":[],"mappings":""}

package/components/identity.roles/operations/list.d.ts

@@ -1,5 +1,2 @@
+import type { Entity } from './lib/Entity';
 export declare function observation(_: unknown, objects: Entity[]): string[];
-interface Entity {
-    role: string;
-}
-export {};

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

@@ -1 +1 @@
-{"version":3,"file":"list.js","sourceRoot":"","sources":["../source/list.ts"],"names":[],"mappings":";;;AAAA,SAAgB,WAAW,CAAE,CAAU,EAAE,OAAiB;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;AACxC,CAAC;AAFD,kCAEC"}
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../source/list.ts"],"names":[],"mappings":";;;AAEA,SAAgB,WAAW,CAAE,CAAU,EAAE,OAAiB;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;AACxC,CAAC;AAFD,kCAEC"}

package/components/identity.roles/operations/principal.d.ts

@@ -1,15 +1,13 @@
-import { type Call } from '@toa.io/types';
+import type { Entity } from './lib/Entity';
+import type { Call } from '@toa.io/types';
+import type { Input as GrantInput } from './grant';
 export declare function effect(input: Identity, context: Context): Promise<void>;
 interface Identity {
     id: string;
 }
 export interface Context {
     local: {
-        transit: Call<void, TransitInput>;
+        grant: Call<Entity, GrantInput>;
     };
 }
-interface TransitInput {
-    identity: string;
-    role: string;
-}
 export {};

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

@@ -2,7 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.effect = void 0;
 async function effect(input, context) {
-    await context.local.transit({ input: { identity: input.id, role: 'system' } });
+    await context.local.grant({
+        input: {
+            identity: input.id,
+            role: 'system'
+        }
+    });
 }
 exports.effect = effect;
 //# sourceMappingURL=principal.js.map

package/components/identity.roles/operations/principal.js.map

@@ -1 +1 @@
-{"version":3,"file":"principal.js","sourceRoot":"","sources":["../source/principal.ts"],"names":[],"mappings":";;;AAEO,KAAK,UAAU,MAAM,CAAE,KAAe,EAAE,OAAgB;IAC7D,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;AAChF,CAAC;AAFD,wBAEC"}
+{"version":3,"file":"principal.js","sourceRoot":"","sources":["../source/principal.ts"],"names":[],"mappings":";;;AAIO,KAAK,UAAU,MAAM,CAAE,KAAe,EAAE,OAAgB;IAC7D,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QACxB,KAAK,EAAE;YACL,QAAQ,EAAE,KAAK,CAAC,EAAE;YAClB,IAAI,EAAE,QAAQ;SACf;KACF,CAAC,CAAA;AACJ,CAAC;AAPD,wBAOC"}