agntcy-dir 1.0.0 → 1.2.0

package/README.md

@@ -105,6 +105,43 @@ const jwtTransport = await Client.createGRPCTransport(jwtConfig);
 const jwtClient = new Client(jwtConfig, jwtTransport);
 ```
 
+### OAuth 2.0 for Directory bearer auth
+
+The SDK supports OIDC/OAuth for Directory bearer authentication on gRPC:
+
+- Interactive login via Authorization Code + PKCE with a loopback callback (`authenticateOAuthPkce()`)
+- Pre-issued access token via `DIRECTORY_CLIENT_AUTH_TOKEN`
+
+Interactive PKCE sessions are cached alongside other Directory tooling at `$XDG_CONFIG_HOME/dirctl/auth-token.json` or `~/.config/dirctl/auth-token.json`. Pre-issued tokens from configuration are used directly and are not written to the cache by the constructor.
+
+Use this mode when your deployment expects a **Bearer access token** on gRPC (for example via a gateway that validates OIDC tokens). Register your IdP application with a **redirect URI** that matches `DIRECTORY_CLIENT_OIDC_REDIRECT_URI` exactly (for example `http://localhost:8484/callback`). The SDK starts a short-lived HTTP server on loopback to receive the authorization redirect.
+
+Some IdPs use **public clients** with PKCE; your IdP may still expect a `client_secret` field in configuration. In that case, use a **random placeholder** from environment variables, not a real secret in source code.
+
+**Important:** The default in-repo Envoy authorization stack validates **GitHub** tokens. OIDC access tokens from your IdP only work if your environment’s gateway or auth service is configured to accept them.
+
+```bash
+export DIRECTORY_CLIENT_AUTH_MODE="oidc"
+export DIRECTORY_CLIENT_SERVER_ADDRESS="directory.example.com:443"
+export DIRECTORY_CLIENT_OIDC_ISSUER="https://your-idp-provider.example.com"
+export DIRECTORY_CLIENT_OIDC_CLIENT_ID="your-app-client-id"
+# Optional placeholder for public clients:
+export DIRECTORY_CLIENT_OIDC_CLIENT_SECRET="random-non-secret-string"
+export DIRECTORY_CLIENT_OIDC_REDIRECT_URI="http://localhost:8484/callback"
+# Optional: comma-separated scopes
+# export DIRECTORY_CLIENT_OIDC_SCOPES="openid,profile,email"
+```
+
+```js
+import { Client } from 'agntcy-dir';
+
+// After exporting the variables above (or building a Config with authMode: 'oidc'):
+const client = new Client();
+await client.authenticateOAuthPkce();
+```
+
+For custom transports, call `Client.createGRPCTransport(oidcConfig, { oidcTokenHolder })` with an `OAuthTokenHolder` (exported from this package). The usual path is `new Client(oidcConfig)`, which wires the holder and transport automatically.
+
 ## Getting Started
 
 ### Prerequisites

package/dist/agntcy-dir.d.ts

@@ -9,6 +9,8 @@ import type { Message } from '@bufbuild/protobuf';
 import type { Timestamp } from '@bufbuild/protobuf/wkt';
 import { Transport } from '@connectrpc/connect';
 
+export declare type AuthMode = '' | 'x509' | 'jwt' | 'tls' | 'oidc';
+
 /**
  * Supporting credential type definitions
  *
@@ -32,6 +34,35 @@ declare type BasicAuthCredentials = Message<"agntcy.dir.store.v1.BasicAuthCreden
  */
 declare const BasicAuthCredentialsSchema: GenMessage<BasicAuthCredentials>;
 
+export declare class CachedToken {
+    accessToken: string;
+    tokenType: string;
+    provider: string;
+    issuer: string;
+    refreshToken: string;
+    expiresAt: Date | undefined;
+    user: string;
+    userId: string;
+    email: string;
+    createdAt: Date | undefined;
+    constructor(accessToken: string, tokenType?: string, provider?: string, issuer?: string, refreshToken?: string, expiresAt?: Date | undefined, user?: string, userId?: string, email?: string, createdAt?: Date | undefined);
+    static fromJson(payload: CachedTokenJson): CachedToken;
+    toJson(): Record<string, string>;
+}
+
+declare interface CachedTokenJson {
+    access_token: string;
+    token_type?: string;
+    provider?: string;
+    issuer?: string;
+    refresh_token?: string;
+    expires_at?: string;
+    user?: string;
+    user_id?: string;
+    email?: string;
+    created_at?: string;
+}
+
 /**
  * High-level client for interacting with AGNTCY Directory services.
  *
@@ -62,6 +93,7 @@ export declare class Client {
     syncClient: Client_2<typeof models_2.store_v1.SyncService>;
     eventClient: Client_2<typeof models_2.events_v1.EventService>;
     namingClient: Client_2<typeof models_2.naming_v1.NamingService>;
+    private oauthHolder;
     /**
      * Initialize the client with the given configuration.
      *
@@ -87,10 +119,21 @@ export declare class Client {
     constructor(config?: Config);
     constructor(config?: Config, grpcTransport?: Transport);
     private static convertToPEM;
-    static createGRPCTransport(config: Config): Promise<Transport>;
+    private static secureNodeOptions;
+    private static createOidcTransport;
+    static createGRPCTransport(config: Config, oidcOptions?: {
+        oidcTokenHolder: OAuthTokenHolder;
+    }): Promise<Transport>;
     private static createX509Transport;
     private static createJWTTransport;
     private static createTLSTransport;
+    private cachedTokenFromResponse;
+    /**
+     * Run browser-based OAuth 2.0 Authorization Code + PKCE login (loopback callback).
+     *
+     * Requires `authMode: 'oidc'`, `oidcIssuer`, and `oidcClientId`.
+     */
+    authenticateOAuthPkce(): Promise<void>;
     /**
      * Request generator helper function for streaming requests.
      */
@@ -357,6 +400,8 @@ export declare class Client {
      * The verification process uses the external dirctl command-line tool
      * to perform the actual cryptographic operations.
      *
+     * When fromServer is true, uses the server's cached verification result.
+     *
      * @param request - VerifyRequest containing the record reference and verification parameters.
      *                  The provider can specify either key-based verification (with a public key)
      *                  or OIDC-based verification
@@ -373,7 +418,8 @@ export declare class Client {
      * console.log(`Signature valid: ${response.success}`);
      * ```
      */
-    verify(request: models_2.sign_v1.VerifyRequest): models_2.sign_v1.VerifyResponse;
+    verify(request: models_2.sign_v1.VerifyRequest): Promise<models_2.sign_v1.VerifyResponse>;
+    private _verifyViaServer;
     /**
      * Create a new synchronization configuration.
      *
@@ -655,28 +701,50 @@ export declare class Config {
     static DEFAULT_DIRCTL_PATH: string;
     static DEFAULT_SPIFFE_ENDPOINT_SOCKET: string;
     static DEFAULT_AUTH_MODE: string;
+    static DEFAULT_AUTH_TOKEN: string;
     static DEFAULT_JWT_AUDIENCE: string;
     static DEFAULT_TLS_CA_FILE: string;
     static DEFAULT_TLS_CERT_FILE: string;
     static DEFAULT_TLS_KEY_FILE: string;
+    static DEFAULT_TLS_SERVER_NAME: string;
+    static DEFAULT_TLS_SKIP_VERIFY: boolean;
+    static DEFAULT_OIDC_ISSUER: string;
+    static DEFAULT_OIDC_CLIENT_ID: string;
+    static DEFAULT_OIDC_CLIENT_SECRET: string;
+    static DEFAULT_OIDC_REDIRECT_URI: string;
+    static DEFAULT_OIDC_CALLBACK_PORT: number;
+    static DEFAULT_OIDC_AUTH_TIMEOUT: number;
+    static DEFAULT_OIDC_SCOPES: string[];
     serverAddress: string;
     dirctlPath: string;
     spiffeEndpointSocket: string;
-    authMode: '' | 'x509' | 'jwt' | 'tls';
+    authMode: AuthMode;
+    authToken: string;
+    /** Backward-compatible alias for `authToken`. */
+    oidcAccessToken: string;
     jwtAudience: string;
     tlsCaFile: string;
     tlsCertFile: string;
     tlsKeyFile: string;
+    tlsServerName: string;
+    tlsSkipVerify: boolean;
+    oidcIssuer: string;
+    oidcClientId: string;
+    oidcClientSecret: string;
+    oidcRedirectUri: string;
+    oidcCallbackPort: number;
+    oidcAuthTimeout: number;
+    oidcScopes: string[];
     /**
      * Creates a new Config instance.
      *
      * @param serverAddress - The server address to connect to. Defaults to '127.0.0.1:8888'
      * @param dirctlPath - Path to the dirctl executable. Defaults to 'dirctl'
      * @param spiffeEndpointSocket - Path to the spire server socket. Defaults to empty string.
-     * @param authMode - Authentication mode: '' for insecure, 'x509', 'jwt' or 'tls'. Defaults to ''
+     * @param authMode - Authentication mode: '' for insecure, 'x509', 'jwt', 'tls', or 'oidc'. Defaults to ''
      * @param jwtAudience - JWT audience for JWT authentication. Required when authMode is 'jwt'
      */
-    constructor(serverAddress?: string, dirctlPath?: string, spiffeEndpointSocket?: string, authMode?: '' | 'x509' | 'jwt' | 'tls', jwtAudience?: string, tlsCaFile?: string, tlsCertFile?: string, tlsKeyFile?: string);
+    constructor(serverAddress?: string, dirctlPath?: string, spiffeEndpointSocket?: string, authMode?: AuthMode, jwtAudience?: string, tlsCaFile?: string, tlsCertFile?: string, tlsKeyFile?: string, authToken?: string, tlsServerName?: string, tlsSkipVerify?: boolean, oidcIssuer?: string, oidcClientId?: string, oidcClientSecret?: string, oidcRedirectUri?: string, oidcCallbackPort?: number, oidcAuthTimeout?: number, oidcScopes?: string[] | undefined, oidcAccessToken?: string | undefined);
     /**
      * Load configuration from environment variables.
      *
@@ -790,6 +858,58 @@ declare type CreateSyncResponse = Message<"agntcy.dir.store.v1.CreateSyncRespons
  */
 declare const CreateSyncResponseSchema: GenMessage<CreateSyncResponse>;
 
+/**
+ * @generated from message agntcy.dir.store.v1.DeleteReferrerRequest
+ */
+declare type DeleteReferrerRequest = Message<"agntcy.dir.store.v1.DeleteReferrerRequest"> & {
+    /**
+     * The record the referrer(s) are referring to.
+     *
+     * @generated from field: agntcy.dir.core.v1.RecordRef record = 1;
+     */
+    record?: RecordRef;
+
+    /**
+     * The CID of the referrer to delete.
+     * If set, delete the referrer by CID.
+     *
+     * @generated from field: optional agntcy.dir.core.v1.ReferrerRef referrer_ref = 2;
+     */
+    referrerRef?: ReferrerRef;
+
+    /**
+     * The referrer type of the referrers to delete.
+     * If set, delete the referrers with given type.
+     *
+     * @generated from field: optional string referrer_type = 3;
+     */
+    referrerType?: string;
+};
+
+/**
+ * Describes the message agntcy.dir.store.v1.DeleteReferrerRequest.
+ * Use `create(DeleteReferrerRequestSchema)` to create a new message.
+ */
+declare const DeleteReferrerRequestSchema: GenMessage<DeleteReferrerRequest>;
+
+/**
+ * @generated from message agntcy.dir.store.v1.DeleteReferrerResponse
+ */
+declare type DeleteReferrerResponse = Message<"agntcy.dir.store.v1.DeleteReferrerResponse"> & {
+    /**
+     * The CID(s) of the deleted referrers.
+     *
+     * @generated from field: repeated agntcy.dir.core.v1.ReferrerRef referrer_refs = 1;
+     */
+    referrerRefs: ReferrerRef[];
+};
+
+/**
+ * Describes the message agntcy.dir.store.v1.DeleteReferrerResponse.
+ * Use `create(DeleteReferrerResponseSchema)` to create a new message.
+ */
+declare const DeleteReferrerResponseSchema: GenMessage<DeleteReferrerResponse>;
+
 /**
  * DeleteSyncRequest specifies which synchronization to delete.
  *
@@ -1693,6 +1813,17 @@ declare const NamingService: GenService<{
     },
 }>;
 
+export declare class OAuthPkceError extends Error {
+    constructor(message: string);
+}
+
+export declare class OAuthTokenHolder {
+    private accessToken;
+    setTokens(accessToken: string): void;
+    updateFromTokenResponse(payload: Record<string, unknown>): void;
+    getAccessToken(): string;
+}
+
 /**
  * @generated from message agntcy.dir.routing.v1.Peer
  */
@@ -1949,6 +2080,13 @@ declare type PullReferrerRequest = Message<"agntcy.dir.store.v1.PullReferrerRequ
      * @generated from field: optional string referrer_type = 2;
      */
     referrerType?: string;
+
+    /**
+     * If set, return the given referrer.
+     *
+     * @generated from field: optional agntcy.dir.core.v1.ReferrerRef referrer_ref = 3;
+     */
+    referrerRef?: ReferrerRef;
 };
 
 /**
@@ -1991,11 +2129,34 @@ declare type PushReferrerRequest = Message<"agntcy.dir.store.v1.PushReferrerRequ
     recordRef?: RecordRef;
 
     /**
-     * RecordReferrer object to be stored for the record
+     * The type of the referrer.
+     * For example, "agntcy.dir.sign.v1.Signature" for signatures.
      *
-     * @generated from field: agntcy.dir.core.v1.RecordReferrer referrer = 2;
+     * @generated from field: string type = 2;
      */
-    referrer?: RecordReferrer;
+    type: string;
+
+    /**
+     * Annotations attached to the referrer object.
+     *
+     * @generated from field: map<string, string> annotations = 3;
+     */
+    annotations: { [key: string]: string };
+
+    /**
+     * Creation timestamp of the record in the RFC3339 format.
+     * Specs: https://www.rfc-editor.org/rfc/rfc3339.html
+     *
+     * @generated from field: string created_at = 4;
+     */
+    createdAt: string;
+
+    /**
+     * The actual data of the referrer.
+     *
+     * @generated from field: google.protobuf.Struct data = 5;
+     */
+    data?: JsonObject;
 };
 
 /**
@@ -2023,6 +2184,13 @@ declare type PushReferrerResponse = Message<"agntcy.dir.store.v1.PushReferrerRes
      * @generated from field: optional string error_message = 2;
      */
     errorMessage?: string;
+
+    /**
+     * The CID of the referrer
+     *
+     * @generated from field: agntcy.dir.core.v1.ReferrerRef referrer_ref = 3;
+     */
+    referrerRef?: ReferrerRef;
 };
 
 /**
@@ -2291,6 +2459,14 @@ declare enum RecordQueryType {
      * @generated from enum value: RECORD_QUERY_TYPE_VERIFIED = 13;
      */
     VERIFIED = 13,
+
+    /**
+     * Query for trusted records (signature verification passed).
+     * Boolean field - use "true" or "false" as value.
+     *
+     * @generated from enum value: RECORD_QUERY_TYPE_TRUSTED = 14;
+     */
+    TRUSTED = 14,
 }
 
 /**
@@ -2407,6 +2583,13 @@ declare type RecordReferrer = Message<"agntcy.dir.core.v1.RecordReferrer"> & {
      * @generated from field: google.protobuf.Struct data = 5;
      */
     data?: JsonObject;
+
+    /**
+     * The CID of the referrer.
+     *
+     * @generated from field: agntcy.dir.core.v1.ReferrerRef referrer_ref = 6;
+     */
+    referrerRef?: ReferrerRef;
 };
 
 /**
@@ -2443,6 +2626,19 @@ declare const RecordRefsSchema: GenMessage<RecordRefs>;
  */
 declare const RecordSchema: GenMessage<Record_2>;
 
+/**
+ * @generated from message agntcy.dir.core.v1.ReferrerRef
+ */
+declare type ReferrerRef = Message<"agntcy.dir.core.v1.ReferrerRef"> & {
+    /**
+     * Content Identifier (https://github.com/multiformats/cid)
+     * A self-describing, content-addressed identifier
+     *
+     * @generated from field: string cid = 1;
+     */
+    cid: string;
+};
+
 /**
  * @generated from message agntcy.dir.store.v1.RequestRegistryCredentialsRequest
  */
@@ -3371,6 +3567,10 @@ export declare namespace store_v1 {
         PullReferrerRequestSchema,
         PullReferrerResponse,
         PullReferrerResponseSchema,
+        DeleteReferrerRequest,
+        DeleteReferrerRequestSchema,
+        DeleteReferrerResponse,
+        DeleteReferrerResponseSchema,
         StoreService,
         file_agntcy_dir_store_v1_sync_service,
         CreateSyncRequest,
@@ -3481,6 +3681,16 @@ declare const StoreService: GenService<{
         input: typeof PullReferrerRequestSchema;
         output: typeof PullReferrerResponseSchema;
     },
+    /**
+     * DeleteReferrer performs delete operation for record referrers.
+     *
+     * @generated from rpc agntcy.dir.store.v1.StoreService.DeleteReferrer
+     */
+    deleteReferrer: {
+        methodKind: "bidi_streaming";
+        input: typeof DeleteReferrerRequestSchema;
+        output: typeof DeleteReferrerResponseSchema;
+    },
 }>;
 
 /**
@@ -3614,6 +3824,19 @@ declare enum SyncStatus {
  */
 declare const SyncStatusSchema: GenEnum<SyncStatus>;
 
+export declare const TOKEN_CACHE_FILE = "auth-token.json";
+
+export declare class TokenCache {
+    readonly cacheDir: string;
+    constructor(cacheDir?: string);
+    getCachePath(): string;
+    load(): CachedToken | undefined;
+    save(token: CachedToken): void;
+    clear(): void;
+    isValid(token: CachedToken | undefined): boolean;
+    getValidToken(): CachedToken | undefined;
+}
+
 /**
  * @generated from message agntcy.dir.routing.v1.UnpublishRequest
  */
@@ -3753,6 +3976,14 @@ declare type VerifyRequest = Message<"agntcy.dir.sign.v1.VerifyRequest"> & {
      * @generated from field: agntcy.dir.sign.v1.VerifyRequestProvider provider = 2;
      */
     provider?: VerifyRequestProvider;
+
+    /**
+     * When true, use cached verification result from server.
+     * When false, verification is performed locally.
+     *
+     * @generated from field: bool from_server = 3;
+     */
+    fromServer: boolean;
 };
 
 /**