@flarcos/kiota-authentication-gnap 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# @flarcos/kiota-authentication-gnap
+
+GNAP ([RFC 9635](https://www.rfc-editor.org/rfc/rfc9635.html)) authentication provider for [Microsoft Kiota](https://github.com/microsoft/kiota)-generated API clients.
+
+Enables Kiota-generated SDKs to authenticate with APIs that use the Grant Negotiation and Authorization Protocol (GNAP), such as [Open Payments](https://openpayments.dev/).
+
+## Features
+
+- ✅ **Kiota `AuthenticationProvider` interface** — drop-in integration
+- ✅ **RFC 9635 GNAP** — full grant lifecycle (request, continue, rotate, revoke)
+- ✅ **RFC 9421 HTTP Message Signatures** — Ed25519 request signing
+- ✅ **RFC 9530 Content-Digest** — SHA-256 body integrity
+- ✅ **RFC 7638 JWK Thumbprint** — automatic key ID derivation
+- ✅ **Token caching** — in-memory store with TTL expiration
+- ✅ **Interactive grants** — pluggable `InteractionHandler` for redirect flows
+
+## Installation
+
+```bash
+npm install @flarcos/kiota-authentication-gnap @microsoft/kiota-abstractions
+```
+
+## Quick Start
+
+```typescript
+import { GnapAuthenticationProvider } from "@flarcos/kiota-authentication-gnap";
+import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
+import fs from "node:fs";
+
+// Create the GNAP auth provider
+const authProvider = new GnapAuthenticationProvider({
+  authServerUrl: "https://auth.wallet.example/.gnap",
+  privateKey: fs.readFileSync("private-key.pem", "utf-8"),
+  clientIdentifier: "https://wallet.example/alice",
+  accessRights: [
+    { type: "incoming-payment", actions: ["create", "read"] },
+    { type: "outgoing-payment", actions: ["create", "read"] },
+    { type: "quote", actions: ["create", "read"] },
+  ],
+});
+
+// Use with a Kiota-generated client
+const adapter = new FetchRequestAdapter(authProvider);
+// const client = new OpenPaymentsClient(adapter);
+```
+
+## Usage with Open Payments
+
+Open Payments uses GNAP for authorization. Here's how to create a payment:
+
+```typescript
+import { GnapAuthenticationProvider } from "@flarcos/kiota-authentication-gnap";
+
+const authProvider = new GnapAuthenticationProvider({
+  // The receiving wallet's auth server
+  authServerUrl: "https://auth.interledger-test.dev/",
+  // Your Ed25519 private key (PEM format)
+  privateKey: process.env.PRIVATE_KEY!,
+  // Your wallet address URL
+  clientIdentifier: "https://ilp.interledger-test.dev/alice",
+  // Request access to create incoming payments
+  accessRights: [
+    {
+      type: "incoming-payment",
+      actions: ["create", "read", "complete"],
+      identifier: "https://ilp.interledger-test.dev/bob",
+    },
+  ],
+});
+```
+
+### Interactive Grants (with user consent)
+
+For operations that require user interaction (e.g., outgoing payments), provide an `InteractionHandler`:
+
+```typescript
+import type { InteractionHandler, InteractionResult } from "@flarcos/kiota-authentication-gnap";
+
+class MyInteractionHandler implements InteractionHandler {
+  async handleRedirect(redirectUrl: string, nonce: string): Promise<InteractionResult> {
+    // Open browser for user to approve
+    console.log(`Please visit: ${redirectUrl}`);
+
+    // Wait for callback and return the interact_ref
+    return {
+      interactRef: "received-interact-ref",
+      hash: "received-hash",
+    };
+  }
+}
+
+const authProvider = new GnapAuthenticationProvider({
+  authServerUrl: "https://auth.interledger-test.dev/",
+  privateKey: process.env.PRIVATE_KEY!,
+  clientIdentifier: "https://ilp.interledger-test.dev/alice",
+  accessRights: [
+    {
+      type: "outgoing-payment",
+      actions: ["create", "read"],
+      identifier: "https://ilp.interledger-test.dev/alice",
+    },
+  ],
+  interact: {
+    start: ["redirect"],
+    finish: {
+      method: "redirect",
+      uri: "http://localhost:3000/callback",
+      nonce: crypto.randomUUID(),
+    },
+  },
+  interactionHandler: new MyInteractionHandler(),
+});
+```
+
+## API Reference
+
+### `GnapAuthenticationProvider`
+
+Main class implementing Kiota's `AuthenticationProvider`.
+
+#### Constructor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `authServerUrl` | `string` | ✅ | Authorization Server grant endpoint |
+| `privateKey` | `string` | ✅ | Ed25519 private key (PEM format) |
+| `clientIdentifier` | `string` | ✅ | Client identifier (wallet address URL) |
+| `accessRights` | `GnapAccessRight[]` | ✅ | Access rights to request |
+| `interact` | `object` | ❌ | Interaction mode configuration |
+| `interactionHandler` | `InteractionHandler` | ❌ | Handler for interactive grants |
+| `tokenStore` | `GnapTokenStore` | ❌ | Token cache (defaults to in-memory) |
+| `allowedHosts` | `string[]` | ❌ | Restrict auth to specific hosts |
+
+#### Methods
+
+- `authenticateRequest(request)` — Authenticate a Kiota request (called automatically)
+- `rotateToken()` — Manually rotate the current access token
+- `revokeToken()` — Revoke the current access token
+
+### Standalone Utilities
+
+```typescript
+import {
+  createHttpSignature,     // RFC 9421 signing
+  computeContentDigest,    // RFC 9530 body hash
+  computeJwkThumbprint,    // RFC 7638 key ID
+  loadPrivateKey,          // PEM → KeyObject
+} from "@flarcos/kiota-authentication-gnap";
+```
+
+## How It Works
+
+When `authenticateRequest` is called, the provider:
+
+1. **Checks the token cache** for a valid, non-expired GNAP access token
+2. **Negotiates a new grant** if no cached token exists (POST to AS)
+3. **Handles interaction** if the AS requires user consent (via `InteractionHandler`)
+4. **Sets the `Authorization: GNAP <token>` header** on the request
+5. **Computes `Content-Digest`** (SHA-256) for requests with a body
+6. **Signs the request** with RFC 9421 HTTP Message Signatures (Ed25519)
+
+## Standards Compliance
+
+| Standard | Description | Coverage |
+|----------|-------------|----------|
+| [RFC 9635](https://www.rfc-editor.org/rfc/rfc9635.html) | GNAP Core Protocol | §2 Grant Request, §3 Response, §5 Continuation, §6 Token Management |
+| [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) | HTTP Message Signatures | §2 Signature Base, §3 Creating Signatures (Ed25519) |
+| [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html) | Content-Digest | SHA-256 digest |
+| [RFC 7638](https://www.rfc-editor.org/rfc/rfc7638.html) | JWK Thumbprint | SHA-256 thumbprint for key identification |
+
+## Project Structure
+
+```
+src/
+├── index.ts                      # Public exports
+├── gnapAuthenticationProvider.ts  # Kiota AuthenticationProvider implementation
+├── gnapAccessTokenProvider.ts    # GNAP grant lifecycle
+├── gnapTokenStore.ts             # In-memory token cache
+├── httpMessageSigner.ts          # RFC 9421 HTTP Message Signatures
+├── contentDigest.ts              # RFC 9530 Content-Digest
+├── keyManagement.ts              # Ed25519 key utilities
+├── types.ts                      # Type definitions
+└── errors.ts                     # Error classes
+```
+
+## License
+
+Apache-2.0
+
+## Acknowledgements
+
+This package was created as part of the [Interledger Foundation Open Payments SDK Grant Program](https://interledger.org/grant/open-payments-sdk).

package/dist/contentDigest.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RFC 9530 Content-Digest computation.
+ * @see https://www.rfc-editor.org/rfc/rfc9530.html
+ */
+/**
+ * Compute the Content-Digest header value for an HTTP request body.
+ * Uses SHA-256 as required by Open Payments.
+ *
+ * @param body - The request body as a Buffer or Uint8Array
+ * @returns The Content-Digest header value (e.g. "sha-256=:base64value:")
+ */
+export declare function computeContentDigest(body: Uint8Array): string;
+/**
+ * Compute Content-Digest from a string body (UTF-8 encoded).
+ */
+export declare function computeContentDigestFromString(body: string): string;
+//# sourceMappingURL=contentDigest.d.ts.map

package/dist/contentDigest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentDigest.d.ts","sourceRoot":"","sources":["../src/contentDigest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAG7D;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/contentDigest.js

@@ -0,0 +1,23 @@
+/**
+ * RFC 9530 Content-Digest computation.
+ * @see https://www.rfc-editor.org/rfc/rfc9530.html
+ */
+import { createHash } from "node:crypto";
+/**
+ * Compute the Content-Digest header value for an HTTP request body.
+ * Uses SHA-256 as required by Open Payments.
+ *
+ * @param body - The request body as a Buffer or Uint8Array
+ * @returns The Content-Digest header value (e.g. "sha-256=:base64value:")
+ */
+export function computeContentDigest(body) {
+    const hash = createHash("sha-256").update(body).digest("base64");
+    return `sha-256=:${hash}:`;
+}
+/**
+ * Compute Content-Digest from a string body (UTF-8 encoded).
+ */
+export function computeContentDigestFromString(body) {
+    return computeContentDigest(Buffer.from(body, "utf-8"));
+}
+//# sourceMappingURL=contentDigest.js.map

package/dist/contentDigest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentDigest.js","sourceRoot":"","sources":["../src/contentDigest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAgB;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjE,OAAO,YAAY,IAAI,GAAG,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAAC,IAAY;IACzD,OAAO,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GNAP-specific error classes.
+ */
+export declare class GnapError extends Error {
+    readonly code?: string | undefined;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined);
+}
+export declare class GnapGrantError extends GnapError {
+    constructor(code: string, description?: string);
+}
+export declare class GnapInteractionRequiredError extends GnapError {
+    readonly redirectUrl: string;
+    readonly continueUri: string;
+    readonly continueAccessToken: string;
+    readonly finishNonce?: string | undefined;
+    constructor(redirectUrl: string, continueUri: string, continueAccessToken: string, finishNonce?: string | undefined);
+}
+export declare class GnapTokenExpiredError extends GnapError {
+    constructor();
+}
+export declare class GnapSignatureError extends GnapError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,SAAU,SAAQ,KAAK;aAGhB,IAAI,CAAC,EAAE,MAAM;aACb,UAAU,CAAC,EAAE,MAAM;gBAFnC,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAI/C;AAED,qBAAa,4BAA6B,SAAQ,SAAS;aAEvC,WAAW,EAAE,MAAM;aACnB,WAAW,EAAE,MAAM;aACnB,mBAAmB,EAAE,MAAM;aAC3B,WAAW,CAAC,EAAE,MAAM;gBAHpB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,EAC3B,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC;AAED,qBAAa,qBAAsB,SAAQ,SAAS;;CAKnD;AAED,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,46 @@
+/**
+ * GNAP-specific error classes.
+ */
+export class GnapError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = "GnapError";
+    }
+}
+export class GnapGrantError extends GnapError {
+    constructor(code, description) {
+        super(description ?? `GNAP grant error: ${code}`, code);
+        this.name = "GnapGrantError";
+    }
+}
+export class GnapInteractionRequiredError extends GnapError {
+    redirectUrl;
+    continueUri;
+    continueAccessToken;
+    finishNonce;
+    constructor(redirectUrl, continueUri, continueAccessToken, finishNonce) {
+        super("GNAP grant requires user interaction");
+        this.redirectUrl = redirectUrl;
+        this.continueUri = continueUri;
+        this.continueAccessToken = continueAccessToken;
+        this.finishNonce = finishNonce;
+        this.name = "GnapInteractionRequiredError";
+    }
+}
+export class GnapTokenExpiredError extends GnapError {
+    constructor() {
+        super("GNAP access token has expired");
+        this.name = "GnapTokenExpiredError";
+    }
+}
+export class GnapSignatureError extends GnapError {
+    constructor(message) {
+        super(message);
+        this.name = "GnapSignatureError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGhB;IACA;IAHlB,YACE,OAAe,EACC,IAAa,EACb,UAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAS;QACb,eAAU,GAAV,UAAU,CAAS;QAGnC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC3C,YAAY,IAAY,EAAE,WAAoB;QAC5C,KAAK,CAAC,WAAW,IAAI,qBAAqB,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,SAAS;IAEvC;IACA;IACA;IACA;IAJlB,YACkB,WAAmB,EACnB,WAAmB,EACnB,mBAA2B,EAC3B,WAAoB;QAEpC,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAL9B,gBAAW,GAAX,WAAW,CAAQ;QACnB,gBAAW,GAAX,WAAW,CAAQ;QACnB,wBAAmB,GAAnB,mBAAmB,CAAQ;QAC3B,gBAAW,GAAX,WAAW,CAAS;QAGpC,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IAClD;QACE,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/gnapAccessTokenProvider.d.ts

@@ -0,0 +1,50 @@
+/**
+ * GNAP Access Token Provider.
+ * Handles the full GNAP (RFC 9635) grant lifecycle:
+ * - Grant request (§2)
+ * - Grant continuation (§5)
+ * - Token rotation (§6.1)
+ * - Token revocation (§6.2)
+ *
+ * All requests to the Authorization Server are signed with RFC 9421.
+ */
+import type { KeyObject } from "node:crypto";
+import type { GnapGrantRequest, GnapAccessToken, GnapAccessRight } from "./types.js";
+export interface GrantRequestParams {
+    /** Authorization Server grant endpoint URL */
+    authServerUrl: string;
+    /** Client identifier (wallet address URL) */
+    clientIdentifier: string;
+    /** Client public key in JWK format */
+    clientKeyJwk: JsonWebKey;
+    /** Client private key for signing */
+    privateKey: KeyObject;
+    /** JWK thumbprint key ID */
+    keyId: string;
+    /** Access rights to request */
+    accessRights: GnapAccessRight[];
+    /** Interaction configuration */
+    interact?: GnapGrantRequest["interact"];
+}
+export declare class GnapAccessTokenProvider {
+    /**
+     * Request a new grant from the Authorization Server.
+     * Returns the access token for non-interactive grants,
+     * or throws GnapInteractionRequiredError if user consent is needed.
+     */
+    requestGrant(params: GrantRequestParams): Promise<GnapAccessToken>;
+    /**
+     * Continue a grant after user interaction (§5.1).
+     * Called with the interact_ref obtained from the interaction callback.
+     */
+    continueGrant(continueUri: string, continueAccessToken: string, interactRef: string, privateKey: KeyObject, keyId: string): Promise<GnapAccessToken>;
+    /**
+     * Rotate an access token (§6.1).
+     */
+    rotateToken(manageUrl: string, existingToken: string, privateKey: KeyObject, keyId: string): Promise<GnapAccessToken>;
+    /**
+     * Revoke an access token (§6.2).
+     */
+    revokeToken(manageUrl: string, existingToken: string, privateKey: KeyObject, keyId: string): Promise<void>;
+}
+//# sourceMappingURL=gnapAccessTokenProvider.d.ts.map

package/dist/gnapAccessTokenProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gnapAccessTokenProvider.d.ts","sourceRoot":"","sources":["../src/gnapAccessTokenProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,KAAK,EACV,gBAAgB,EAEhB,eAAe,EACf,eAAe,EAEhB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,YAAY,EAAE,UAAU,CAAC;IACzB,qCAAqC;IACrC,UAAU,EAAE,SAAS,CAAC;IACtB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,gCAAgC;IAChC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;CACzC;AAED,qBAAa,uBAAuB;IAClC;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IA4FxE;;;OAGG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,EAC3B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,SAAS,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,CAAC;IAmD3B;;OAEG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,CAAC;IAkC3B;;OAEG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;CA6BjB"}

package/dist/gnapAccessTokenProvider.js

@@ -0,0 +1,176 @@
+/**
+ * GNAP Access Token Provider.
+ * Handles the full GNAP (RFC 9635) grant lifecycle:
+ * - Grant request (§2)
+ * - Grant continuation (§5)
+ * - Token rotation (§6.1)
+ * - Token revocation (§6.2)
+ *
+ * All requests to the Authorization Server are signed with RFC 9421.
+ */
+import { createHttpSignature } from "./httpMessageSigner.js";
+import { computeContentDigestFromString } from "./contentDigest.js";
+import { GnapGrantError, GnapInteractionRequiredError } from "./errors.js";
+export class GnapAccessTokenProvider {
+    /**
+     * Request a new grant from the Authorization Server.
+     * Returns the access token for non-interactive grants,
+     * or throws GnapInteractionRequiredError if user consent is needed.
+     */
+    async requestGrant(params) {
+        const { authServerUrl, clientIdentifier, clientKeyJwk, privateKey, keyId, accessRights, interact, } = params;
+        // Build the GNAP grant request body (§2)
+        // Open Payments uses a simplified client format:
+        // - string: wallet address URL (backwards compatible)
+        // - { walletAddress: "..." }: wallet address in object form
+        // - { jwk: {...} }: directed identity (non-interactive only)
+        const grantRequest = {
+            access_token: {
+                access: accessRights,
+            },
+            client: clientIdentifier,
+        };
+        if (interact) {
+            grantRequest.interact = interact;
+        }
+        const body = JSON.stringify(grantRequest);
+        // Compute Content-Digest
+        const contentDigest = computeContentDigestFromString(body);
+        // Build headers
+        const headers = new Map();
+        headers.set("content-type", "application/json");
+        headers.set("content-digest", contentDigest);
+        headers.set("content-length", Buffer.byteLength(body).toString());
+        // Sign the request (RFC 9421)
+        const { signature, signatureInput } = await createHttpSignature({
+            privateKey,
+            keyId,
+            method: "POST",
+            targetUri: authServerUrl,
+            headers,
+            hasBody: true,
+        });
+        // Send the grant request
+        const response = await fetch(authServerUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Digest": contentDigest,
+                "Content-Length": Buffer.byteLength(body).toString(),
+                Signature: signature,
+                "Signature-Input": signatureInput,
+            },
+            body,
+        });
+        const grantResponse = (await response.json());
+        // Handle error response
+        if (grantResponse.error) {
+            throw new GnapGrantError(grantResponse.error.code, grantResponse.error.description);
+        }
+        // Non-interactive: access token returned directly
+        if (grantResponse.access_token) {
+            return grantResponse.access_token;
+        }
+        // Interactive: AS requires user consent
+        if (grantResponse.interact?.redirect && grantResponse.continue) {
+            throw new GnapInteractionRequiredError(grantResponse.interact.redirect, grantResponse.continue.uri, grantResponse.continue.access_token.value, grantResponse.interact.finish);
+        }
+        throw new GnapGrantError("invalid_grant_response", `Unexpected grant response (HTTP ${response.status}): no access_token or interact field`);
+    }
+    /**
+     * Continue a grant after user interaction (§5.1).
+     * Called with the interact_ref obtained from the interaction callback.
+     */
+    async continueGrant(continueUri, continueAccessToken, interactRef, privateKey, keyId) {
+        const body = JSON.stringify({ interact_ref: interactRef });
+        const contentDigest = computeContentDigestFromString(body);
+        const headers = new Map();
+        headers.set("content-type", "application/json");
+        headers.set("content-digest", contentDigest);
+        headers.set("content-length", Buffer.byteLength(body).toString());
+        headers.set("authorization", `GNAP ${continueAccessToken}`);
+        const { signature, signatureInput } = await createHttpSignature({
+            privateKey,
+            keyId,
+            method: "POST",
+            targetUri: continueUri,
+            headers,
+            hasBody: true,
+        });
+        const response = await fetch(continueUri, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Digest": contentDigest,
+                "Content-Length": Buffer.byteLength(body).toString(),
+                Authorization: `GNAP ${continueAccessToken}`,
+                Signature: signature,
+                "Signature-Input": signatureInput,
+            },
+            body,
+        });
+        const grantResponse = (await response.json());
+        if (grantResponse.error) {
+            throw new GnapGrantError(grantResponse.error.code, grantResponse.error.description);
+        }
+        if (grantResponse.access_token) {
+            return grantResponse.access_token;
+        }
+        throw new GnapGrantError("invalid_continue_response", `Continue response did not include access_token (HTTP ${response.status})`);
+    }
+    /**
+     * Rotate an access token (§6.1).
+     */
+    async rotateToken(manageUrl, existingToken, privateKey, keyId) {
+        const headers = new Map();
+        headers.set("authorization", `GNAP ${existingToken}`);
+        const { signature, signatureInput } = await createHttpSignature({
+            privateKey,
+            keyId,
+            method: "POST",
+            targetUri: manageUrl,
+            headers,
+            hasBody: false,
+        });
+        const response = await fetch(manageUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `GNAP ${existingToken}`,
+                Signature: signature,
+                "Signature-Input": signatureInput,
+            },
+        });
+        const tokenResponse = (await response.json());
+        if (!tokenResponse.value) {
+            throw new GnapGrantError("invalid_rotation_response", `Token rotation failed (HTTP ${response.status})`);
+        }
+        return tokenResponse;
+    }
+    /**
+     * Revoke an access token (§6.2).
+     */
+    async revokeToken(manageUrl, existingToken, privateKey, keyId) {
+        const headers = new Map();
+        headers.set("authorization", `GNAP ${existingToken}`);
+        const { signature, signatureInput } = await createHttpSignature({
+            privateKey,
+            keyId,
+            method: "DELETE",
+            targetUri: manageUrl,
+            headers,
+            hasBody: false,
+        });
+        const response = await fetch(manageUrl, {
+            method: "DELETE",
+            headers: {
+                Authorization: `GNAP ${existingToken}`,
+                Signature: signature,
+                "Signature-Input": signatureInput,
+            },
+        });
+        if (!response.ok) {
+            throw new GnapGrantError("revocation_failed", `Token revocation failed (HTTP ${response.status})`);
+        }
+    }
+}
+//# sourceMappingURL=gnapAccessTokenProvider.js.map

package/dist/gnapAccessTokenProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gnapAccessTokenProvider.js","sourceRoot":"","sources":["../src/gnapAccessTokenProvider.ts"],"names":[],"mappings":"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"}

package/dist/gnapAuthenticationProvider.d.ts

@@ -0,0 +1,68 @@
+/**
+ * GNAP Authentication Provider for Kiota.
+ *
+ * Implements the Kiota AuthenticationProvider interface to authenticate
+ * requests using the GNAP protocol (RFC 9635) with HTTP Message Signatures
+ * (RFC 9421).
+ *
+ * This is the main entry point for the package. Usage:
+ *
+ * ```typescript
+ * import { GnapAuthenticationProvider } from "@flarcos/kiota-authentication-gnap";
+ *
+ * const authProvider = new GnapAuthenticationProvider({
+ *   authServerUrl: "https://auth.wallet.example/.well-known/...",
+ *   privateKey: fs.readFileSync("private-key.pem", "utf-8"),
+ *   clientIdentifier: "https://wallet.example/alice",
+ *   accessRights: [{ type: "outgoing-payment", actions: ["create", "read"] }],
+ * });
+ *
+ * const adapter = new FetchRequestAdapter(authProvider);
+ * const client = new OpenPaymentsClient(adapter);
+ * ```
+ */
+import type { AuthenticationProvider } from "@microsoft/kiota-abstractions";
+import type { RequestInformation } from "@microsoft/kiota-abstractions";
+import type { GnapAuthenticationProviderOptions, GnapAccessToken } from "./types.js";
+export declare class GnapAuthenticationProvider implements AuthenticationProvider {
+    private readonly authServerUrl;
+    private readonly clientIdentifier;
+    private readonly accessRights;
+    private readonly interact;
+    private readonly interactionHandler?;
+    private readonly tokenStore;
+    private readonly allowedHosts;
+    private readonly tokenProvider;
+    private keyPromise;
+    private readonly rawKey;
+    constructor(options: GnapAuthenticationProviderOptions);
+    /**
+     * Lazily initialize the key material.
+     */
+    private getKeyMaterial;
+    /**
+     * Authenticate a Kiota request by:
+     * 1. Obtaining/caching a GNAP access token
+     * 2. Setting the Authorization: GNAP header
+     * 3. Computing Content-Digest for request bodies
+     * 4. Signing the request with HTTP Message Signatures
+     */
+    authenticateRequest: (request: RequestInformation, additionalAuthenticationContext?: Record<string, unknown>) => Promise<void>;
+    /**
+     * Get an access token — either from cache or by negotiating a new grant.
+     */
+    private getAccessToken;
+    /**
+     * Handle interactive grants (redirect-based user consent).
+     */
+    private handleInteraction;
+    /**
+     * Rotate the current access token.
+     */
+    rotateToken(): Promise<GnapAccessToken>;
+    /**
+     * Revoke the current access token.
+     */
+    revokeToken(): Promise<void>;
+}
+//# sourceMappingURL=gnapAuthenticationProvider.d.ts.map

package/dist/gnapAuthenticationProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gnapAuthenticationProvider.d.ts","sourceRoot":"","sources":["../src/gnapAuthenticationProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAexE,OAAO,KAAK,EACV,iCAAiC,EAIjC,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,0BAA2B,YAAW,sBAAsB;IACvE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoD;IACjF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IAGxD,OAAO,CAAC,UAAU,CAID;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,OAAO,EAAE,iCAAiC;IAYtD;;OAEG;YACW,cAAc;IAW5B;;;;;;OAMG;IACH,mBAAmB,GACjB,SAAS,kBAAkB,EAC3B,kCAAkC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACxD,OAAO,CAAC,IAAI,CAAC,CA0Dd;IAEF;;OAEG;YACW,cAAc;IAuC5B;;OAEG;YACW,iBAAiB;IAuC/B;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IA8B7C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAmBnC"}