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

package/components/identity.grants/operations/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './code.js';
+export * from './identify.js';
+export type * from '../../types/index.js';

package/components/identity.grants/operations/lib/index.js

@@ -0,0 +1,3 @@
+export * from './code.js';
+export * from './identify.js';
+//# sourceMappingURL=index.js.map

package/components/identity.grants/operations/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

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

@@ -0,0 +1,13 @@
+import type { Operation } from '@toa.io/bridges.node';
+import type { Context, Entity } from './lib/index.js';
+/** What a user has allowed, for a screen that lets them take it back. */
+export declare class Computation implements Operation {
+    private enumerate;
+    mount(context: Context): void;
+    execute(input: Input): Promise<Entity[]>;
+}
+interface Input {
+    authority: string;
+    identity: string;
+}
+export {};

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

@@ -0,0 +1,18 @@
+import { quote } from '@toa.io/generic';
+/** What a user has allowed, for a screen that lets them take it back. */
+export class Computation {
+    enumerate;
+    mount(context) {
+        this.enumerate = context.local.enumerate;
+    }
+    async execute(input) {
+        return await this.enumerate({
+            query: {
+                criteria: `authority==${quote(input.authority)};identity==${quote(input.identity)}`,
+                limit: LIMIT
+            }
+        });
+    }
+}
+const LIMIT = 256;
+//# sourceMappingURL=list.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../source/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAIvC,yEAAyE;AACzE,MAAM,OAAO,WAAW;IACd,SAAS,CAAgC;IAE1C,KAAK,CAAE,OAAgB;QAC5B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAA;IAC1C,CAAC;IAEM,KAAK,CAAC,OAAO,CAAE,KAAY;QAChC,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC;YAC1B,KAAK,EAAE;gBACL,QAAQ,EAAE,cAAc,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,cAAc,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE;gBACnF,KAAK,EAAE,KAAK;aACb;SACF,CAAC,CAAA;IACJ,CAAC;CACF;AAED,MAAM,KAAK,GAAG,GAAG,CAAA"}

package/components/identity.grants/operations/revoke.d.ts

@@ -0,0 +1,18 @@
+import type { Maybe } from '@toa.io/core';
+import type { Operation } from '@toa.io/bridges.node';
+import type { Context, Entity } from './lib/index.js';
+/**
+ * Taking back what was allowed. The token itself is not deleted — it is out in the world —
+ * so what is revoked is the key it was issued under, which is what `identity.tokens` reads
+ * it with. It stops being a token within `identity.tokens.cache.ttl`.
+ */
+export declare class Transition implements Operation {
+    private keys;
+    mount(context: Context): void;
+    execute(input: Input, object: Entity): Promise<Maybe<void>>;
+}
+interface Input {
+    authority: string;
+    identity: string;
+}
+export {};

package/components/identity.grants/operations/revoke.js

@@ -0,0 +1,25 @@
+/**
+ * Taking back what was allowed. The token itself is not deleted — it is out in the world —
+ * so what is revoked is the key it was issued under, which is what `identity.tokens` reads
+ * it with. It stops being a token within `identity.tokens.cache.ttl`.
+ */
+export class Transition {
+    keys;
+    mount(context) {
+        this.keys = context.remote.identity.keys;
+    }
+    async execute(input, object) {
+        // the id is a route parameter, so a grant of another identity is asked for by anyone
+        // who guesses one; the authority and the identity are what say it is theirs
+        if (object._version === 0 || object.authority !== input.authority ||
+            object.identity !== input.identity)
+            return ERR_NOT_FOUND;
+        if (object.kid !== undefined)
+            await this.keys.disable({ query: { id: object.kid } });
+        object.revokedAt = Date.now();
+    }
+}
+const ERR_NOT_FOUND = new (class NotFoundError extends Error {
+    code = 'NOT_FOUND';
+})();
+//# sourceMappingURL=revoke.js.map

package/components/identity.grants/operations/revoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revoke.js","sourceRoot":"","sources":["../source/revoke.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACb,IAAI,CAAwC;IAE7C,KAAK,CAAE,OAAgB;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;IAC1C,CAAC;IAEM,KAAK,CAAC,OAAO,CAAE,KAAY,EAAE,MAAc;QAChD,qFAAqF;QACrF,4EAA4E;QAC5E,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;YAC/D,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;YAClC,OAAO,aAAa,CAAA;QAEtB,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;YAC1B,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;QAExD,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAC/B,CAAC;CACF;AAED,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,aAAc,SAAQ,KAAK;IAC1C,IAAI,GAAG,WAAW,CAAA;CACnC,CAAC,EAAE,CAAA"}

package/components/identity.grants/source/authorize.ts

@@ -0,0 +1,90 @@
+import { hold, identify } from './lib/index.js'
+import type { Maybe } from '@toa.io/core'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context } from './lib/index.js'
+
+/**
+ * What the consent page calls when a user allows a client. The page holds the user's own
+ * credentials, so this is the user's own route; the code it answers with is what the client
+ * redeems at the token endpoint.
+ *
+ * The grant is recorded so a user can see what they allowed and take it back. It is not
+ * consulted to skip the prompt — consent is asked every time, which is what keeps a client
+ * that changed where it wants a code sent from being waved through on an older one.
+ */
+export class Effect implements Operation {
+  private context!: Context
+
+  public mount (context: Context): void {
+    this.context = context
+  }
+
+  public async execute (input: Input): Promise<Maybe<Output>> {
+    const { authority, identity } = input
+
+    if (input.method !== S256)
+      return invalid('invalid_request', 'Only the S256 code challenge method is supported')
+
+    const client = await this.context.remote.identity.clients.describe({
+      input: { authority, id: input.client, redirect: input.redirect }
+    })
+
+    if (client instanceof Error)
+      return invalid('invalid_client', 'No such client')
+
+    if (client.permitted !== true)
+      return invalid('invalid_request', 'The redirect is not one this client may receive a code at')
+
+    const scope = input.scope ?? []
+
+    // recorded on the grant and carried to the token endpoint, and restricting nothing yet:
+    // a token carries the rights of the identity that consented, over every path it may
+    // reach. What binds it is a `permissions` argument in `exchange`, see documentation/oauth.md
+    const resource = input.resource ?? []
+
+    const grant = await this.context.local.transit({
+      query: { id: identify(authority, identity, input.client) },
+      input: { authority, identity, client: input.client, scope, resource }
+    })
+
+    if (grant instanceof Error)
+      return grant
+
+    const code = await hold(authority, {
+      identity,
+      client: input.client,
+      redirect: input.redirect,
+      challenge: input.challenge,
+      scope,
+      resource
+    }, this.context)
+
+    return { code, expires_in: this.context.configuration.lifetime }
+  }
+}
+
+function invalid (error: string, description: string): Output {
+  return { status: BAD_REQUEST, error, error_description: description }
+}
+
+const S256 = 'S256'
+const BAD_REQUEST = 400
+
+interface Input {
+  authority: string
+  identity: string
+  client: string
+  redirect: string
+  challenge: string
+  method: string
+  scope?: string[]
+  resource?: string[]
+}
+
+interface Output {
+  status?: number
+  code?: string
+  expires_in?: number
+  error?: string
+  error_description?: string
+}

package/components/identity.grants/source/exchange.ts

@@ -0,0 +1,130 @@
+import { identify, spend, verifies } from './lib/index.js'
+import type { Maybe } from '@toa.io/core'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Code, Context } from './lib/index.js'
+
+/**
+ * The token endpoint, RFC 6749 §4.1.3. Anonymous, because the clients this server knows are
+ * public ones with no secret to authenticate with: what stands in for that is PKCE, since
+ * only the client that began the flow holds the verifier the challenge was made from.
+ *
+ * Every failure here is `invalid_grant` without saying which check failed. A code that was
+ * replayed, a verifier that does not match and a redirect that was swapped are all the same
+ * answer, and telling them apart would say whether a stolen code was still live.
+ */
+export class Effect implements Operation {
+  private context!: Context
+
+  public mount (context: Context): void {
+    this.context = context
+  }
+
+  public async execute (input: Input): Promise<Maybe<Output>> {
+    const { authority } = input
+
+    if (input.grant_type !== AUTHORIZATION_CODE)
+      return invalid('unsupported_grant_type', 'Only the authorization code grant is supported')
+
+    if (input.code === undefined || input.code_verifier === undefined)
+      return invalid('invalid_request', 'A code and a code verifier are required')
+
+    // spent first: a wrong verifier burns the code, which is what stops it being guessed at
+    const code = await spend(authority, input.code, this.context)
+
+    if (code === null || !this.redeemable(code, input))
+      return invalid('invalid_grant', 'The authorization code is not redeemable')
+
+    // `permissions` would bind the token to `code.resource` — `{'/mcp/**': ['*']}` for a
+    // resource at `/mcp/`, which `permits()` reads on every request. Left unset: the token
+    // carries the rights of the identity that consented, see documentation/oauth.md#audience
+    const issued = await this.context.remote.identity.tokens.issue({
+      input: {
+        authority,
+        identity: code.identity,
+        label: label(code.client),
+        lifetime: this.context.configuration.token,
+        ...(code.scope.length === 0 ? {} : { scopes: code.scope })
+      }
+    })
+
+    // the only refusal `issue` makes is a scope the consenting identity does not hold, and
+    // what it says about that is its own; the client is told what it may act on
+    if (issued instanceof Error)
+      return invalid('invalid_scope', 'The requested scope is not one the identity holds')
+
+    // the key the token was issued under, so revoking the grant revokes the token. The token
+    // is already out, so a grant that fails to record it is logged rather than unwound — it
+    // costs the user the ability to revoke, and refusing here would cost them the token too
+    const grant = await this.context.local.transit({
+      query: { id: identify(authority, code.identity, code.client) },
+      input: {
+        authority,
+        identity: code.identity,
+        client: code.client,
+        scope: code.scope,
+        resource: code.resource,
+        kid: issued.kid
+      }
+    })
+
+    if (grant instanceof Error)
+      this.context.logs.error('Grant not recorded for an issued token',
+        { client: code.client, kid: issued.kid })
+
+    return {
+      // RFC 6749 §5.1 asks for 200, where a POST would otherwise answer 201
+      status: OK,
+      access_token: issued.token,
+      token_type: 'Bearer',
+      ...(issued.exp === undefined
+        ? {}
+        : { expires_in: Math.floor((issued.exp - Date.now()) / 1000) }),
+      ...(code.scope.length === 0 ? {} : { scope: code.scope.join(' ') })
+    }
+  }
+
+  private redeemable (code: Code, input: Input): boolean {
+    if (!verifies(code.challenge, input.code_verifier!))
+      return false
+
+    // RFC 6749 §4.1.3: what was sent to `authorize` must be sent again
+    if (input.redirect_uri !== undefined && input.redirect_uri !== code.redirect)
+      return false
+
+    return input.client_id === undefined || input.client_id === code.client
+  }
+}
+
+/** `identity.tokens` requires one, and it is what a user sees when listing what they issued. */
+function label (client: string): string {
+  return client.slice(0, LABEL)
+}
+
+function invalid (error: string, description: string): Output {
+  return { status: BAD_REQUEST, error, error_description: description }
+}
+
+const AUTHORIZATION_CODE = 'authorization_code'
+const OK = 200
+const BAD_REQUEST = 400
+const LABEL = 64
+
+interface Input {
+  authority: string
+  grant_type: string
+  code?: string
+  code_verifier?: string
+  redirect_uri?: string
+  client_id?: string
+  resource?: string | string[]
+}
+
+interface Output {
+  status?: number
+  access_token?: string
+  token_type?: string
+  expires_in?: number
+  scope?: string
+  error?: string
+  error_description?: string
+}

package/components/identity.grants/source/lib/code.ts

@@ -0,0 +1,39 @@
+import { createHash, randomBytes } from 'node:crypto'
+import type { Code, Context } from '../../types/index.js'
+
+/**
+ * An authorization code is a bearer credential that lives for seconds. It is held under a
+ * hash of itself, so a dump of the store hands out none of them, and redeemed with `GETDEL`,
+ * so it is spent once however many requests arrive at once — the property the whole flow
+ * rests on, since a replayed code is a stolen grant.
+ */
+export async function hold (authority: string, code: Code, context: Context): Promise<string> {
+  const value = randomBytes(32).toString('base64url')
+
+  await context.stash.set(key(authority, value), JSON.stringify(code),
+    'EX', context.configuration.lifetime)
+
+  return value
+}
+
+export async function spend (authority: string, value: string, context: Context): Promise<Code | null> {
+  const held = await context.stash.getdel(key(authority, value))
+
+  return held === null ? null : JSON.parse(held) as Code
+}
+
+/**
+ * PKCE, RFC 7636: the client kept a verifier and sent its hash, and only the client that
+ * began the flow can present the verifier now. `S256` alone — `plain` proves nothing.
+ */
+export function verifies (challenge: string, verifier: string): boolean {
+  return digest(verifier) === challenge
+}
+
+export function digest (verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url')
+}
+
+function key (authority: string, value: string): string {
+  return `oauth:code:${authority}:${createHash('sha256').update(value).digest('hex')}`
+}

package/components/identity.grants/source/lib/identify.ts

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * A user holds one grant per client, so the record is addressed by the three things that
+ * say which: authorizing again replaces what is there rather than leaving another row, and
+ * revoking has one thing to revoke.
+ */
+export function identify (authority: string, identity: string, client: string): string {
+  return createHash('sha256')
+    .update(JSON.stringify([authority, identity, client]))
+    .digest('hex')
+    .slice(0, LENGTH)
+}
+
+/** What the entity prototype accepts as an id. */
+const LENGTH = 32

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

@@ -0,0 +1,3 @@
+export * from './code.js'
+export * from './identify.js'
+export type * from '../../types/index.js'

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

@@ -0,0 +1,28 @@
+import { quote } from '@toa.io/generic'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Entity } from './lib/index.js'
+
+/** What a user has allowed, for a screen that lets them take it back. */
+export class Computation implements Operation {
+  private enumerate!: Context['local']['enumerate']
+
+  public mount (context: Context): void {
+    this.enumerate = context.local.enumerate
+  }
+
+  public async execute (input: Input): Promise<Entity[]> {
+    return await this.enumerate({
+      query: {
+        criteria: `authority==${quote(input.authority)};identity==${quote(input.identity)}`,
+        limit: LIMIT
+      }
+    })
+  }
+}
+
+const LIMIT = 256
+
+interface Input {
+  authority: string
+  identity: string
+}

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

@@ -0,0 +1,38 @@
+import type { Maybe } from '@toa.io/core'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Entity } from './lib/index.js'
+
+/**
+ * Taking back what was allowed. The token itself is not deleted — it is out in the world —
+ * so what is revoked is the key it was issued under, which is what `identity.tokens` reads
+ * it with. It stops being a token within `identity.tokens.cache.ttl`.
+ */
+export class Transition implements Operation {
+  private keys!: Context['remote']['identity']['keys']
+
+  public mount (context: Context): void {
+    this.keys = context.remote.identity.keys
+  }
+
+  public async execute (input: Input, object: Entity): Promise<Maybe<void>> {
+    // the id is a route parameter, so a grant of another identity is asked for by anyone
+    // who guesses one; the authority and the identity are what say it is theirs
+    if (object._version === 0 || object.authority !== input.authority ||
+      object.identity !== input.identity)
+      return ERR_NOT_FOUND
+
+    if (object.kid !== undefined)
+      await this.keys.disable({ query: { id: object.kid } })
+
+    object.revokedAt = Date.now()
+  }
+}
+
+const ERR_NOT_FOUND = new (class NotFoundError extends Error {
+  public readonly code = 'NOT_FOUND'
+})()
+
+interface Input {
+  authority: string
+  identity: string
+}

package/components/identity.grants/tsconfig.json

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