Merge pull request decentralized-identity#82 from decentralized-identity/feat/oauth-authorization-server-adapter

feat(oauth): authorization-server adapter seam with generic-OIDC reference adapter

Author: H0BB5

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to @kya-os/mcp will be documented here.
 Format: https://keepachangelog.com/en/1.0.0/
 Versioning: https://semver.org/spec/v2.0.0.html
 
+## [Unreleased]
+
+### Added
+
+- `./authz` authorization seam: a neutral, method-agnostic
+  `AuthorizationServerAdapter` port with a shared dispatch predicate, an
+  `AuthorizationServerRegistry` that routes a tool's protection to one adapter,
+  and a generic-OIDC reference adapter under `authz/oidc/` (mandatory S256 PKCE,
+  RFC 8707 resource binding, injectable fetch seam — no named vendor IdP, per
+  the donation's vendor-neutrality). The `AuthorizationRequirement` union
+  (`oauth`/`mdl`/`idv`/`credential`/`none`) anticipates further adapters as
+  siblings of `oidc/`.
+- `AccountabilityContext` projection (agent → accountable-admin → user →
+  intent) that feeds the policy principal's `responsibleParty`; `orgRootDid` is
+  a forward-compatible slot pending the organization root identity.
+- A deterministic, network-free in-memory OIDC example exercising the full
+  authorization path. Additive; no new runtime dependency (zod, jose, Web
+  Crypto only).
+
 ## [1.5.0] - 2026-06-01
 
 Exposes the policy-request projection as a reusable primitive and adds a

package.json

@@ -47,6 +47,10 @@
       "types": "./dist/policy/index.d.ts",
       "default": "./dist/policy/index.js"
     },
+    "./authz": {
+      "types": "./dist/authz/index.d.ts",
+      "default": "./dist/authz/index.js"
+    },
     "./schemas/*.json": "./schemas/*.json",
     "./package.json": "./package.json"
   },

src/authz/__tests__/accountability.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { projectAccountability, accountabilityToPolicyPrincipal } from '../accountability.js';
+import type { DelegationCredentialSubject } from '../../types/protocol.js';
+
+/**
+ * AccountabilityContext is the agent -> accountable-admin -> user -> intent
+ * chain. It is a read-only projection from a delegation credential subject and
+ * feeds PolicyRequest.principal, so policy can gate on accountability. The
+ * admin rung is sourced from the credential `controller` until a dedicated
+ * org-admin field lands; `orgRootDid` is a forward-compatible slot that stays
+ * undefined until the Org Root DID work exists.
+ */
+
+function subject(over: Partial<DelegationCredentialSubject['delegation']> = {}): DelegationCredentialSubject {
+  return {
+    id: 'did:key:zAgent',
+    delegation: {
+      id: 'del-1',
+      issuerDid: 'did:web:org.example',
+      subjectDid: 'did:key:zAgent',
+      userDid: 'did:web:user.example',
+      controller: 'did:web:org.example:admins:alice',
+      scopes: ['vault:read'],
+      constraints: {},
+      status: 'active',
+      ...over,
+    } as DelegationCredentialSubject['delegation'],
+  };
+}
+
+describe('projectAccountability', () => {
+  it('projects agent, user, intent scopes, and the admin from controller', () => {
+    const ctx = projectAccountability(subject());
+    expect(ctx.agentDid).toBe('did:key:zAgent');
+    expect(ctx.userDid).toBe('did:web:user.example');
+    expect(ctx.accountableAdminDid).toBe('did:web:org.example:admins:alice');
+    expect(ctx.scopes).toEqual(['vault:read']);
+  });
+
+  it('leaves orgRootDid undefined (Org Root DID not yet landed)', () => {
+    expect(projectAccountability(subject()).orgRootDid).toBeUndefined();
+  });
+
+  it('omits accountableAdminDid when no controller is present', () => {
+    const ctx = projectAccountability(subject({ controller: undefined }));
+    expect(ctx.accountableAdminDid).toBeUndefined();
+  });
+
+  it('defaults scopes to an empty array when none are delegated', () => {
+    expect(projectAccountability(subject({ scopes: undefined })).scopes).toEqual([]);
+  });
+});
+
+describe('accountabilityToPolicyPrincipal', () => {
+  it('maps the accountable admin onto PolicyRequest principal.responsibleParty', () => {
+    const principal = accountabilityToPolicyPrincipal(projectAccountability(subject()));
+    expect(principal.agentDid).toBe('did:key:zAgent');
+    expect(principal.responsibleParty).toBe('did:web:org.example:admins:alice');
+  });
+
+  it('omits responsibleParty when there is no accountable admin', () => {
+    const principal = accountabilityToPolicyPrincipal(
+      projectAccountability(subject({ controller: undefined })),
+    );
+    expect(principal.agentDid).toBe('did:key:zAgent');
+    expect('responsibleParty' in principal).toBe(false);
+  });
+});

src/authz/__tests__/adapter.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import {
+  requirementMatchesAdapter,
+  type AuthorizationServerAdapter,
+} from '../adapter.js';
+import type { ToolProtection } from '../requirement.js';
+
+/**
+ * AuthorizationServerAdapter is the neutral, one-responsibility port: given a
+ * tool's protection, decide whether this adapter must run, produce a
+ * challenge, and consume the result. `requirementMatchesAdapter` is the shared
+ * dispatch predicate every adapter's `isRequired` is built on — exercised here
+ * as real runtime code (the interface alone is erased at runtime).
+ */
+
+const protect = (toolName: string, requirement: ToolProtection['requirement']): ToolProtection => ({
+  toolName,
+  requirement,
+});
+
+describe('requirementMatchesAdapter', () => {
+  it('matches when the protection requirement type equals the adapter type', () => {
+    expect(
+      requirementMatchesAdapter('oauth', protect('vault.read', { type: 'oauth', provider: 'generic-oidc' })),
+    ).toBe(true);
+  });
+
+  it('does not match an unprotected tool (type none)', () => {
+    expect(requirementMatchesAdapter('oauth', protect('ping', { type: 'none' }))).toBe(false);
+  });
+
+  it('does not match when another adapter type owns the requirement', () => {
+    expect(requirementMatchesAdapter('oauth', protect('verify.id', { type: 'idv' }))).toBe(false);
+  });
+});
+
+describe('AuthorizationServerAdapter (contract)', () => {
+  it('a conforming adapter wires isRequired to the shared predicate', () => {
+    const adapter: AuthorizationServerAdapter = {
+      type: 'oauth',
+      isRequired: (protection) => requirementMatchesAdapter('oauth', protection),
+      async initiateFlow() {
+        throw new Error('not exercised in this test');
+      },
+      async verifyAuthorization() {
+        throw new Error('not exercised in this test');
+      },
+    };
+    expect(adapter.type).toBe('oauth');
+    expect(adapter.isRequired(protect('vault.read', { type: 'oauth', provider: 'generic-oidc' }))).toBe(true);
+    expect(adapter.isRequired(protect('ping', { type: 'none' }))).toBe(false);
+  });
+});

src/authz/__tests__/example-inmemory.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { runInMemoryAuthorizationFlow } from '../examples/inmemory-oidc.js';
+
+/**
+ * End-to-end showcase of the authorization seam with zero network: a registry
+ * holding the generic-OIDC reference adapter wired to an in-memory token
+ * endpoint. Deterministic and CI-safe — it is the reliable demonstration that
+ * the pluggable adapter pattern works edge to edge (protect a tool -> resolve
+ * an adapter -> challenge -> verify -> delegation outcome -> policy principal).
+ */
+describe('in-memory OIDC authorization flow', () => {
+  it('routes a protected tool through challenge, verification, and a policy principal', async () => {
+    const outcome = await runInMemoryAuthorizationFlow({
+      toolName: 'vault.read',
+      requiredScopes: ['vault:read'],
+      agentDid: 'did:key:zAgent',
+      accountableAdminDid: 'did:web:org.example:admins:alice',
+    });
+
+    // A challenge was produced for the protected tool.
+    expect(outcome.challenge.error).toBe('needs_authorization');
+    expect(new URL(outcome.challenge.authorizationUrl).searchParams.get('code_challenge_method')).toBe('S256');
+
+    // Verification succeeded through the in-memory token endpoint (no network).
+    expect(outcome.result.valid).toBe(true);
+    expect(outcome.result.credential?.agent_did).toBe('did:key:zAgent');
+    expect(outcome.result.credential?.scopes).toContain('vault:read');
+
+    // The accountability chain reached the policy principal.
+    expect(outcome.policyPrincipal.agentDid).toBe('did:key:zAgent');
+    expect(outcome.policyPrincipal.responsibleParty).toBe('did:web:org.example:admins:alice');
+
+    // No external network was used.
+    expect(outcome.networkCalls).toBe(0);
+  });
+
+  it('produces a stable, deterministic result across runs', async () => {
+    const a = await runInMemoryAuthorizationFlow({
+      toolName: 'vault.read',
+      requiredScopes: ['vault:read'],
+      agentDid: 'did:key:zAgent',
+    });
+    const b = await runInMemoryAuthorizationFlow({
+      toolName: 'vault.read',
+      requiredScopes: ['vault:read'],
+      agentDid: 'did:key:zAgent',
+    });
+    expect(a.result.credential?.scopes).toEqual(b.result.credential?.scopes);
+    expect(a.result.valid).toBe(b.result.valid);
+  });
+});

src/authz/__tests__/index.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import * as oauth from '../index.js';
+
+/**
+ * The ./oauth barrel is the package's public authorization surface. This test
+ * pins the exported value identifiers so an accidental removal is caught.
+ */
+describe('@kya-os/mcp/authz public surface', () => {
+  it('exports the seam, registry, reference adapter, and helpers', () => {
+    expect(typeof oauth.AuthorizationServerRegistry).toBe('function');
+    expect(typeof oauth.GenericOidcAdapter).toBe('function');
+    expect(typeof oauth.requirementMatchesAdapter).toBe('function');
+    expect(typeof oauth.buildAuthorizeUrl).toBe('function');
+    expect(typeof oauth.verifyS256Challenge).toBe('function');
+    expect(typeof oauth.buildAuthorizationServerMetadata).toBe('function');
+    expect(typeof oauth.projectAccountability).toBe('function');
+    expect(typeof oauth.AuthorizationRequirementSchema).toBe('object');
+  });
+});

src/authz/__tests__/registry.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { AuthorizationServerRegistry } from '../registry.js';
+import { GenericOidcAdapter } from '../oidc/oidc-adapter.js';
+import type { AuthorizationServerAdapter } from '../adapter.js';
+
+/**
+ * The registry routes a tool's protection to exactly one adapter by type, with
+ * a sealed lifecycle — mirroring the provider-registry pattern so the
+ * authorization seam composes the same pluggable way as the policy seam.
+ */
+
+const oidc = () =>
+  new GenericOidcAdapter({
+    type: 'oauth',
+    issuer: 'https://idp.example',
+    authorizationEndpoint: 'https://idp.example/authorize',
+    tokenEndpoint: 'https://idp.example/token',
+    clientId: 'agent-client',
+    scopes: ['openid'],
+  });
+
+describe('AuthorizationServerRegistry', () => {
+  it('registers and resolves an adapter by type', () => {
+    const registry = new AuthorizationServerRegistry();
+    registry.register(oidc());
+    expect(registry.get('oauth')?.type).toBe('oauth');
+    expect(registry.list().map((a) => a.type)).toEqual(['oauth']);
+  });
+
+  it('returns undefined for an unregistered type', () => {
+    expect(new AuthorizationServerRegistry().get('idv')).toBeUndefined();
+  });
+
+  it('rejects registering two adapters for the same type', () => {
+    const registry = new AuthorizationServerRegistry();
+    registry.register(oidc());
+    expect(() => registry.register(oidc())).toThrow(/already registered/i);
+  });
+
+  it('routes a tool protection to the adapter whose type owns it', () => {
+    const registry = new AuthorizationServerRegistry();
+    registry.register(oidc());
+    const adapter = registry.resolve({
+      toolName: 'vault.read',
+      requirement: { type: 'oauth', provider: 'generic-oidc' },
+    });
+    expect(adapter?.type).toBe('oauth');
+  });
+
+  it('resolves to undefined for an unprotected tool', () => {
+    const registry = new AuthorizationServerRegistry();
+    registry.register(oidc());
+    expect(registry.resolve({ toolName: 'ping', requirement: { type: 'none' } })).toBeUndefined();
+  });
+
+  it('seals against further registration', () => {
+    const registry = new AuthorizationServerRegistry();
+    registry.register(oidc());
+    registry.seal();
+    expect(registry.isSealed()).toBe(true);
+    const another: AuthorizationServerAdapter = { ...oidc(), type: 'idv' } as AuthorizationServerAdapter;
+    expect(() => registry.register(another)).toThrow(/sealed/i);
+  });
+});

src/authz/__tests__/requirement.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import {
+  AuthorizationRequirementSchema,
+  ToolProtectionSchema,
+  type AuthorizationRequirement,
+} from '../requirement.js';
+
+/**
+ * The AuthorizationRequirement union is the neutral description of *what kind*
+ * of authorization a tool needs, independent of any concrete authorization
+ * server. It is the input vocabulary the AuthorizationServerAdapter dispatches
+ * on. These tests pin the discriminants and the fail-closed parsing.
+ */
+describe('AuthorizationRequirement', () => {
+  it('accepts an oauth requirement with provider and optional scopes', () => {
+    const parsed = AuthorizationRequirementSchema.parse({
+      type: 'oauth',
+      provider: 'generic-oidc',
+      requiredScopes: ['vault:read'],
+    });
+    expect(parsed.type).toBe('oauth');
+  });
+
+  it('accepts the none requirement (no authorization needed)', () => {
+    expect(AuthorizationRequirementSchema.parse({ type: 'none' }).type).toBe('none');
+  });
+
+  it.each(['mdl', 'idv', 'credential'])('accepts the %s requirement discriminant', (type) => {
+    expect(AuthorizationRequirementSchema.parse({ type }).type).toBe(type);
+  });
+
+  it('rejects an unknown discriminant', () => {
+    expect(() => AuthorizationRequirementSchema.parse({ type: 'telepathy' })).toThrow();
+  });
+
+  it('rejects an oauth requirement missing its provider', () => {
+    expect(() => AuthorizationRequirementSchema.parse({ type: 'oauth' })).toThrow();
+  });
+
+  it('narrows by discriminant at the type level', () => {
+    const req: AuthorizationRequirement = { type: 'oauth', provider: 'generic-oidc' };
+    if (req.type === 'oauth') {
+      // `provider` is only reachable on the oauth variant — compile-time proof
+      // the union discriminates correctly.
+      expect(req.provider).toBe('generic-oidc');
+    }
+  });
+});
+
+describe('ToolProtection', () => {
+  it('parses a tool protection declaring a required authorization', () => {
+    const parsed = ToolProtectionSchema.parse({
+      toolName: 'vault.read',
+      requirement: { type: 'oauth', provider: 'generic-oidc', requiredScopes: ['vault:read'] },
+    });
+    expect(parsed.toolName).toBe('vault.read');
+    expect(parsed.requirement.type).toBe('oauth');
+  });
+
+  it('rejects a tool protection with no tool name', () => {
+    expect(() =>
+      ToolProtectionSchema.parse({ requirement: { type: 'none' } }),
+    ).toThrow();
+  });
+});