tenzro-sdk 0.1.0 → 0.3.0

package/dist/auth.d.ts

@@ -0,0 +1,394 @@
+import { RpcClient } from "./rpc";
+/**
+ * Client for OAuth 2.1 + DPoP onboarding RPCs.
+ *
+ * Onboarding uses OAuth 2.1 (RFC 6749 successor) + DPoP-bound JWTs
+ * (RFC 9449) + Rich Authorization Requests (RFC 9396). Participants —
+ * humans, delegated agents under a human controller, and fully autonomous
+ * agents — onboard via the three RPCs exposed here. Each call provisions
+ * a TDIP identity (+ MPC wallet) and returns a JWT bound to a
+ * holder-supplied DPoP `jkt` (RFC 7638 thumbprint of the holder's
+ * Ed25519 public key).
+ *
+ * Subsequent privileged calls (sign + send transaction, escrow create,
+ * release/refund, etc.) authenticate by sending the JWT in the
+ * `Authorization: DPoP <jwt>` header alongside a per-request DPoP proof
+ * in the `DPoP` header. The SDK forwards both headers automatically when
+ * the `TENZRO_BEARER_JWT` and `TENZRO_DPOP_PROOF` environment variables
+ * are set in Node — see {@link RpcClient} for the transport-level wiring.
+ */
+export declare class AuthClient {
+    private rpc;
+    constructor(rpc: RpcClient);
+    /**
+     * Onboard a new **human** participant — provisions a TDIP `did:tenzro:human:*`
+     * identity, a fresh MPC wallet, and returns an OAuth 2.1 access token.
+     *
+     * @param displayName - human-readable label surfaced in approver UIs
+     * @param dpopJkt - optional RFC 7638 JWK thumbprint of the holder's
+     *   Ed25519 public key. If supplied, the issued JWT is DPoP-bound to
+     *   that key and every subsequent privileged call must accompany the
+     *   bearer with a fresh DPoP proof signed by the same key. Strongly
+     *   recommended.
+     */
+    onboardHuman(displayName: string, dpopJkt?: string): Promise<OnboardSession>;
+    /**
+     * Onboard a **delegated agent** that acts on behalf of an existing
+     * `controllerDid` (typically a human). The agent inherits the
+     * controller's act-chain and is bounded by `delegationScope`.
+     *
+     * Revoking the controller DID via {@link revokeDid} cascades and
+     * invalidates this agent's token automatically.
+     */
+    onboardDelegatedAgent(controllerDid: string, capabilities: string[], delegationScope: unknown, dpopJkt?: string): Promise<OnboardSession>;
+    /**
+     * Onboard a **fully autonomous agent**. Unlike a delegated agent, this
+     * has no human controller — instead the agent must post a TNZO bond
+     * (slashable on misbehaviour) at `bondFundingAddress` before
+     * onboarding succeeds.
+     */
+    onboardAutonomousAgent(bondFundingAddress: string, dpopJkt?: string): Promise<OnboardSession>;
+    /**
+     * Exchange a long-lived refresh token for a fresh access token. Mirrors
+     * OAuth 2.1 `grant_type=refresh_token`. Refresh tokens are opaque UUIDs
+     * with a 30-day TTL; access tokens are HS256 JWTs with a 1-hour TTL.
+     *
+     * If `dpopJkt` is supplied, the new access token is DPoP-bound to that
+     * thumbprint. The refresh token itself is **not** rotated in V1.
+     */
+    refreshToken(refreshToken: string, dpopJkt?: string): Promise<RefreshedToken>;
+    /**
+     * Mint a fresh access + refresh token pair against an existing MPC
+     * wallet. Useful when the holder already provisioned a wallet via
+     * `tenzro_createWallet` and now wants OAuth-style auth credentials
+     * without re-running the full onboarding flow.
+     *
+     * Returns the same shape as the three onboard variants —
+     * {@link OnboardSession} — so it slots into existing session-management
+     * code.
+     */
+    linkWalletForAuth(walletId: string, options?: {
+        dpopJkt?: string;
+        displayName?: string;
+        ttlSecs?: number;
+    }): Promise<OnboardSession>;
+    /**
+     * Revoke a single JWT by its `jti` claim. The token is added to the
+     * engine's revocation set and any subsequent validation fails.
+     */
+    revokeJwt(jti: string, reason?: string): Promise<RevokeResponse>;
+    /**
+     * Revoke an entire identity by DID. Every JWT minted under this DID
+     * (and every descendant DID in the act-chain) is invalidated
+     * transitively.
+     */
+    revokeDid(did: string, reason?: string): Promise<RevokeResponse>;
+    /**
+     * TDIP/GDPR Article 17 right-to-erasure. Hard-deletes a previously
+     * revoked identity from the registry and persistent storage.
+     *
+     * The identity MUST already be `Revoked` — call {@link revokeDid} first,
+     * allow the cascading revocation broadcaster to propagate, and then
+     * call this. Distinct from `revokeDid` which is a logical delete.
+     */
+    forgetIdentity(did: string): Promise<{
+        did: string;
+        status: string;
+        note: string;
+    }>;
+    /**
+     * List approvals in `Pending` status for the given approver DID.
+     * Returns the records the approver should review and decide on.
+     */
+    listPendingApprovals(approverDid: string): Promise<PendingApprovals>;
+    /**
+     * Decide a pending approval — either `"approved"` or `"denied"`. Only
+     * the recorded approver DID may decide; mismatched approvers are
+     * rejected with JSON-RPC error code `-32001` (forbidden).
+     */
+    decideApproval(approvalId: string, decision: "approved" | "denied", approverDid: string): Promise<ApprovalDecision>;
+    /**
+     * Fetch a single approval record by id. The engine lazy-transitions
+     * an expired `Pending` record to `Expired` on this read path, so a
+     * returned `Pending` record is guaranteed to still be live. Returns
+     * JSON-RPC `-32000` if the id is unknown.
+     */
+    getApproval(approvalId: string): Promise<ApprovalRecord>;
+    /**
+     * **RFC 8693 OAuth 2.0 Token Exchange.** Exchange a parent JWT for a
+     * narrower child JWT bound to a different DPoP key, with a strictly
+     * subset of the parent's RAR grants and AAP capabilities. The child
+     * token's `controller_did` is set to the parent's `sub`, extending the
+     * act-chain by one hop.
+     *
+     * Subset enforcement is performed by the AS — `requestedRar` and
+     * `requestedAapCapabilities` must be a strict subset of what the parent
+     * already holds. Anything outside the parent's authority is rejected
+     * with JSON-RPC error code `-32002`.
+     *
+     * @param subjectToken - the parent JWT (validated for signature, exp,
+     *   and revocation by the AS)
+     * @param childBearerDid - DID that will be the `sub` of the child JWT
+     * @param childDpopJkt - RFC 7638 JWK thumbprint of the child holder's
+     *   Ed25519 public key. The child token will be DPoP-bound to it.
+     * @param requestedRar - typed scope envelope (RFC 9396) the child should
+     *   carry. Must be a subset of the parent's `authorization_details`.
+     * @param requestedAapCapabilities - AAP `aap_capabilities` claim list.
+     *   Must be a subset of the parent's capabilities.
+     * @param requestedTtlSecs - optional override; clamped to the engine's
+     *   `max_ttl_secs` and parent's remaining lifetime.
+     */
+    exchangeToken(subjectToken: string, childBearerDid: string, childDpopJkt: string, requestedRar: unknown, requestedAapCapabilities: unknown[], requestedTtlSecs?: number): Promise<TokenExchangeResult>;
+    /**
+     * **RFC 7662 OAuth 2.0 Token Introspection.** Ask the AS whether a
+     * token is currently active and, if so, return its full claim set
+     * (RAR, AAP, cnf, controller_did, etc.). Per RFC 7662 §2.2 a failed
+     * validation returns `{ active: false }` with no other fields — the AS
+     * deliberately does not leak why the token is inactive.
+     *
+     * Use this from a downstream resource server that wants to validate a
+     * bearer token without re-implementing JWT signature checking.
+     */
+    introspectToken(token: string): Promise<IntrospectionResult>;
+    /**
+     * **RFC 8414 / RFC 9728 OAuth Authorization Server / Protected Resource
+     * Metadata.** Returns the same metadata document the AS publishes at
+     * `GET /.well-known/openid-configuration`. Useful for JSON-RPC-only
+     * clients (CLI, agents) that don't want to also speak HTTP discovery.
+     */
+    oauthDiscovery(): Promise<OAuthDiscovery>;
+}
+/**
+ * One of the three onboarding RPCs (or `linkWalletForAuth`) returns this
+ * session bundle.
+ */
+export interface OnboardSession {
+    /** Provisioned TDIP identity record. */
+    identity: unknown;
+    /** Provisioned MPC wallet record (id + address). */
+    wallet: unknown;
+    /**
+     * OAuth 2.1 access token (HS256 JWT, optionally DPoP-bound). Send as
+     * `Authorization: Bearer <token>` on subsequent privileged calls. When
+     * DPoP-bound, also send a fresh `DPoP: <proof>` header.
+     */
+    access_token: string;
+    /** Always `"Bearer"` (RFC 6750 token type, even though DPoP-bound). */
+    token_type?: string;
+    /** Access-token lifetime in seconds (default 3600). */
+    expires_in?: number;
+    /**
+     * Long-lived refresh token (opaque UUID, 30-day TTL). Exchange via
+     * {@link AuthClient.refreshToken} when the access token expires. Treat
+     * as a secret — leakage allows minting access tokens until revocation.
+     */
+    refresh_token?: string;
+    /** Refresh-token lifetime in seconds (default 30 days). */
+    refresh_token_expires_in?: number;
+    /** `true` iff the access token requires a DPoP proof on every call. */
+    dpop_bound?: boolean;
+    /**
+     * RFC 9396 Rich Authorization Request payload echoed back, describing
+     * the act-chain and capabilities the token is authorized for.
+     */
+    authorization_details?: unknown;
+}
+/**
+ * Result of {@link AuthClient.refreshToken}. The refresh token is **not**
+ * rotated in V1 — only the access token changes.
+ */
+export interface RefreshedToken {
+    /** New access-token JWT. */
+    access_token: string;
+    /** Always `"Bearer"`. */
+    token_type?: string;
+    /** Access-token lifetime in seconds. */
+    expires_in?: number;
+    /**
+     * `true` iff the new access token is DPoP-bound (i.e., the request
+     * supplied `dpopJkt` and the engine encoded a `cnf.jkt` claim).
+     */
+    dpop_bound?: boolean;
+}
+/** Result of `revokeJwt` / `revokeDid`. */
+export interface RevokeResponse {
+    /** Engine status string — typically `"revoked"`. */
+    status?: string;
+    /** Number of JTIs invalidated by this call (>1 indicates cascade). */
+    affected_jti_count?: number;
+}
+/** Result of `listPendingApprovals`. */
+export interface PendingApprovals {
+    /** Number of pending records returned. */
+    count?: number;
+    /**
+     * The records themselves — opaque JSON to keep the SDK decoupled
+     * from `tenzro-auth` storage internals.
+     */
+    pending?: unknown[];
+}
+/** Result of `decideApproval`. */
+export interface ApprovalDecision {
+    /** New status — `"Approved"` or `"Denied"`. */
+    status?: string;
+    /** Echo of the approval id. */
+    approval_id?: string;
+}
+/**
+ * Result of `getApproval` — a single approval record. Matches the wire
+ * shape produced by `approval_to_json` in `tenzro-node`.
+ */
+export interface ApprovalRecord {
+    /** Engine-assigned unique identifier for this approval. */
+    approval_id?: string;
+    /** DID that initiated the request and is waiting on a decision. */
+    requester_did?: string;
+    /** DID that must approve or deny the request. */
+    approver_did?: string;
+    /** Creation time (Unix epoch, ms). */
+    created_at_ms?: number;
+    /**
+     * Hard expiry — past this point the engine lazy-transitions the
+     * record to `Expired` on the next read.
+     */
+    expires_at_ms?: number;
+    /**
+     * Lifecycle state as a debug-printed enum string
+     * (`"Pending"` / `"Approved"` / `"Denied"` / `"Expired"`).
+     */
+    status?: string;
+    /** Decision timestamp (Unix epoch, ms). `null`/absent while pending. */
+    decided_at_ms?: number | null;
+    /** Short human-readable summary of the request. */
+    summary?: string;
+    /** Action identifier (free-form, e.g. `"wallet.transfer"`). */
+    action?: string;
+}
+/**
+ * Result of {@link AuthClient.exchangeToken} — the issued child JWT and
+ * its delegation envelope per RFC 8693 §2.2.
+ */
+export interface TokenExchangeResult {
+    /** The newly-issued child JWT (HS256, DPoP-bound to `child_dpop_jkt`). */
+    access_token: string;
+    /** Lifetime of the child token in seconds. */
+    expires_in: number;
+    /** Always `"DPoP"` — child tokens are always DPoP-bound (RFC 9449). */
+    token_type: string;
+    /**
+     * Always `"urn:ietf:params:oauth:token-type:jwt"` — the format of the
+     * issued token (RFC 8693 §2.2).
+     */
+    issued_token_type: string;
+    /**
+     * Echo of the delegation envelope: `{ controller_did, depth, … }`. The
+     * exact shape is defined by `tenzro_auth::TokenExchangeOutcome` — kept
+     * as opaque JSON in the SDK to avoid recapitulating every AAP claim
+     * type.
+     */
+    delegation: unknown;
+}
+/**
+ * Result of {@link AuthClient.introspectToken} — the RFC 7662 §2.2
+ * introspection response. When `active` is `false`, all other fields are
+ * absent (the AS does not leak why the token is inactive).
+ *
+ * The full claim set (RAR `authorization_details`, AAP `aap_*` claims,
+ * `cnf`, `controller_did`, etc.) is returned as flat JSON properties to
+ * keep the SDK decoupled from `tenzro-auth` internals — callers that
+ * need typed access can narrow the fields themselves.
+ */
+export interface IntrospectionResult {
+    /**
+     * `true` iff the token validates and its controller chain is not
+     * revoked.
+     */
+    active: boolean;
+    /** Subject — bearer DID. Present iff `active`. */
+    sub?: string;
+    /** Issuer — node DID. Present iff `active`. */
+    iss?: string;
+    /** Audience — typically the resource server URL. Present iff `active`. */
+    aud?: string;
+    /** Issued-at, Unix seconds. Present iff `active`. */
+    iat?: number;
+    /** Not-before, Unix seconds. Present iff `active`. */
+    nbf?: number;
+    /** Expires-at, Unix seconds. Present iff `active`. */
+    exp?: number;
+    /** JWT id. Present iff `active`. */
+    jti?: string;
+    /** `"DPoP"` for tokens with a `cnf.jkt`; absent otherwise. */
+    token_type?: string;
+    /**
+     * RFC 7800 confirmation claim — `{ jkt: "<thumbprint>" }` for
+     * DPoP-bound tokens.
+     */
+    cnf?: {
+        jkt: string;
+    };
+    /** The authorizing DID (parent of `sub` in the act-chain). */
+    controller_did?: string;
+    /** RFC 9396 typed scope envelope. */
+    authorization_details?: unknown;
+    /** AAP claims — present only when set on the token. */
+    aap_agent?: unknown;
+    aap_task?: unknown;
+    aap_capabilities?: unknown;
+    aap_oversight?: unknown;
+    aap_delegation?: unknown;
+    aap_context?: unknown;
+    aap_audit?: unknown;
+}
+/**
+ * Result of {@link AuthClient.oauthDiscovery} — the OAuth 2.0
+ * authorization-server metadata document (RFC 8414) augmented with the
+ * AAP-specific extensions.
+ *
+ * Mirrors the document published at
+ * `GET /.well-known/openid-configuration` on the AS.
+ */
+export interface OAuthDiscovery {
+    /** Issuer DID — typically `did:tenzro:node:<node_id>`. */
+    issuer: string;
+    /**
+     * `POST` endpoint for authorization-code, refresh-token, and
+     * token-exchange grants.
+     */
+    token_endpoint: string;
+    /** `POST` endpoint for RFC 7662 token introspection. */
+    introspection_endpoint: string;
+    /** `POST` endpoint for RFC 7009 token revocation. */
+    revocation_endpoint: string;
+    /**
+     * All grant types the AS accepts. Includes
+     * `urn:ietf:params:oauth:grant-type:token-exchange`,
+     * `authorization_code`, and `refresh_token`.
+     */
+    grant_types_supported: string[];
+    /**
+     * Authentication methods at the token endpoint (`"none"` for public
+     * clients, `"private_key_jwt"`).
+     */
+    token_endpoint_auth_methods_supported: string[];
+    /** Authorization-code response types — currently `["code"]`. */
+    response_types_supported: string[];
+    /**
+     * DPoP signing algorithms accepted on proofs — currently `["EdDSA"]`
+     * (Ed25519 per RFC 8037).
+     */
+    dpop_signing_alg_values_supported: string[];
+    /**
+     * RFC 9396 RAR `type` values the AS recognises: `transfer`,
+     * `create_escrow`, `discharge_escrow`, `inference`, `stake`, `vote`,
+     * `contract`, `register_identity`.
+     */
+    authorization_details_types_supported: string[];
+    /**
+     * AAP claim names the AS issues — `aap_agent`, `aap_task`,
+     * `aap_capabilities`, `aap_oversight`, `aap_delegation`, `aap_context`,
+     * `aap_audit`.
+     */
+    aap_claims_supported: string[];
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

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

package/dist/auth.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthClient = void 0;
+/**
+ * Client for OAuth 2.1 + DPoP onboarding RPCs.
+ *
+ * Onboarding uses OAuth 2.1 (RFC 6749 successor) + DPoP-bound JWTs
+ * (RFC 9449) + Rich Authorization Requests (RFC 9396). Participants —
+ * humans, delegated agents under a human controller, and fully autonomous
+ * agents — onboard via the three RPCs exposed here. Each call provisions
+ * a TDIP identity (+ MPC wallet) and returns a JWT bound to a
+ * holder-supplied DPoP `jkt` (RFC 7638 thumbprint of the holder's
+ * Ed25519 public key).
+ *
+ * Subsequent privileged calls (sign + send transaction, escrow create,
+ * release/refund, etc.) authenticate by sending the JWT in the
+ * `Authorization: DPoP <jwt>` header alongside a per-request DPoP proof
+ * in the `DPoP` header. The SDK forwards both headers automatically when
+ * the `TENZRO_BEARER_JWT` and `TENZRO_DPOP_PROOF` environment variables
+ * are set in Node — see {@link RpcClient} for the transport-level wiring.
+ */
+class AuthClient {
+    rpc;
+    constructor(rpc) {
+        this.rpc = rpc;
+    }
+    /**
+     * Onboard a new **human** participant — provisions a TDIP `did:tenzro:human:*`
+     * identity, a fresh MPC wallet, and returns an OAuth 2.1 access token.
+     *
+     * @param displayName - human-readable label surfaced in approver UIs
+     * @param dpopJkt - optional RFC 7638 JWK thumbprint of the holder's
+     *   Ed25519 public key. If supplied, the issued JWT is DPoP-bound to
+     *   that key and every subsequent privileged call must accompany the
+     *   bearer with a fresh DPoP proof signed by the same key. Strongly
+     *   recommended.
+     */
+    async onboardHuman(displayName, dpopJkt) {
+        const params = { display_name: displayName };
+        if (dpopJkt)
+            params.dpop_jkt = dpopJkt;
+        return this.rpc.call("tenzro_onboardHuman", params);
+    }
+    /**
+     * Onboard a **delegated agent** that acts on behalf of an existing
+     * `controllerDid` (typically a human). The agent inherits the
+     * controller's act-chain and is bounded by `delegationScope`.
+     *
+     * Revoking the controller DID via {@link revokeDid} cascades and
+     * invalidates this agent's token automatically.
+     */
+    async onboardDelegatedAgent(controllerDid, capabilities, delegationScope, dpopJkt) {
+        const params = {
+            controller_did: controllerDid,
+            capabilities,
+            delegation_scope: delegationScope,
+        };
+        if (dpopJkt)
+            params.dpop_jkt = dpopJkt;
+        return this.rpc.call("tenzro_onboardDelegatedAgent", params);
+    }
+    /**
+     * Onboard a **fully autonomous agent**. Unlike a delegated agent, this
+     * has no human controller — instead the agent must post a TNZO bond
+     * (slashable on misbehaviour) at `bondFundingAddress` before
+     * onboarding succeeds.
+     */
+    async onboardAutonomousAgent(bondFundingAddress, dpopJkt) {
+        const params = {
+            bond_funding_address: bondFundingAddress,
+        };
+        if (dpopJkt)
+            params.dpop_jkt = dpopJkt;
+        return this.rpc.call("tenzro_onboardAutonomousAgent", params);
+    }
+    /**
+     * Exchange a long-lived refresh token for a fresh access token. Mirrors
+     * OAuth 2.1 `grant_type=refresh_token`. Refresh tokens are opaque UUIDs
+     * with a 30-day TTL; access tokens are HS256 JWTs with a 1-hour TTL.
+     *
+     * If `dpopJkt` is supplied, the new access token is DPoP-bound to that
+     * thumbprint. The refresh token itself is **not** rotated in V1.
+     */
+    async refreshToken(refreshToken, dpopJkt) {
+        const params = { refresh_token: refreshToken };
+        if (dpopJkt)
+            params.dpop_jkt = dpopJkt;
+        return this.rpc.call("tenzro_refreshToken", params);
+    }
+    /**
+     * Mint a fresh access + refresh token pair against an existing MPC
+     * wallet. Useful when the holder already provisioned a wallet via
+     * `tenzro_createWallet` and now wants OAuth-style auth credentials
+     * without re-running the full onboarding flow.
+     *
+     * Returns the same shape as the three onboard variants —
+     * {@link OnboardSession} — so it slots into existing session-management
+     * code.
+     */
+    async linkWalletForAuth(walletId, options) {
+        const params = { wallet_id: walletId };
+        if (options?.dpopJkt)
+            params.dpop_jkt = options.dpopJkt;
+        if (options?.displayName)
+            params.display_name = options.displayName;
+        if (options?.ttlSecs)
+            params.ttl_secs = options.ttlSecs;
+        return this.rpc.call("tenzro_linkWalletForAuth", params);
+    }
+    /**
+     * Revoke a single JWT by its `jti` claim. The token is added to the
+     * engine's revocation set and any subsequent validation fails.
+     */
+    async revokeJwt(jti, reason) {
+        return this.rpc.call("tenzro_revokeJwt", {
+            jti,
+            reason: reason ?? "revoked via SDK",
+        });
+    }
+    /**
+     * Revoke an entire identity by DID. Every JWT minted under this DID
+     * (and every descendant DID in the act-chain) is invalidated
+     * transitively.
+     */
+    async revokeDid(did, reason) {
+        return this.rpc.call("tenzro_revokeDid", {
+            did,
+            reason: reason ?? "revoked via SDK",
+        });
+    }
+    /**
+     * TDIP/GDPR Article 17 right-to-erasure. Hard-deletes a previously
+     * revoked identity from the registry and persistent storage.
+     *
+     * The identity MUST already be `Revoked` — call {@link revokeDid} first,
+     * allow the cascading revocation broadcaster to propagate, and then
+     * call this. Distinct from `revokeDid` which is a logical delete.
+     */
+    async forgetIdentity(did) {
+        return this.rpc.call("tenzro_forgetIdentity", { did });
+    }
+    /**
+     * List approvals in `Pending` status for the given approver DID.
+     * Returns the records the approver should review and decide on.
+     */
+    async listPendingApprovals(approverDid) {
+        return this.rpc.call("tenzro_listPendingApprovals", {
+            approver_did: approverDid,
+        });
+    }
+    /**
+     * Decide a pending approval — either `"approved"` or `"denied"`. Only
+     * the recorded approver DID may decide; mismatched approvers are
+     * rejected with JSON-RPC error code `-32001` (forbidden).
+     */
+    async decideApproval(approvalId, decision, approverDid) {
+        return this.rpc.call("tenzro_decideApproval", {
+            approval_id: approvalId,
+            decision,
+            approver_did: approverDid,
+        });
+    }
+    /**
+     * Fetch a single approval record by id. The engine lazy-transitions
+     * an expired `Pending` record to `Expired` on this read path, so a
+     * returned `Pending` record is guaranteed to still be live. Returns
+     * JSON-RPC `-32000` if the id is unknown.
+     */
+    async getApproval(approvalId) {
+        return this.rpc.call("tenzro_getApproval", {
+            approval_id: approvalId,
+        });
+    }
+    /**
+     * **RFC 8693 OAuth 2.0 Token Exchange.** Exchange a parent JWT for a
+     * narrower child JWT bound to a different DPoP key, with a strictly
+     * subset of the parent's RAR grants and AAP capabilities. The child
+     * token's `controller_did` is set to the parent's `sub`, extending the
+     * act-chain by one hop.
+     *
+     * Subset enforcement is performed by the AS — `requestedRar` and
+     * `requestedAapCapabilities` must be a strict subset of what the parent
+     * already holds. Anything outside the parent's authority is rejected
+     * with JSON-RPC error code `-32002`.
+     *
+     * @param subjectToken - the parent JWT (validated for signature, exp,
+     *   and revocation by the AS)
+     * @param childBearerDid - DID that will be the `sub` of the child JWT
+     * @param childDpopJkt - RFC 7638 JWK thumbprint of the child holder's
+     *   Ed25519 public key. The child token will be DPoP-bound to it.
+     * @param requestedRar - typed scope envelope (RFC 9396) the child should
+     *   carry. Must be a subset of the parent's `authorization_details`.
+     * @param requestedAapCapabilities - AAP `aap_capabilities` claim list.
+     *   Must be a subset of the parent's capabilities.
+     * @param requestedTtlSecs - optional override; clamped to the engine's
+     *   `max_ttl_secs` and parent's remaining lifetime.
+     */
+    async exchangeToken(subjectToken, childBearerDid, childDpopJkt, requestedRar, requestedAapCapabilities, requestedTtlSecs) {
+        const params = {
+            subject_token: subjectToken,
+            child_bearer_did: childBearerDid,
+            child_dpop_jkt: childDpopJkt,
+            requested_rar: requestedRar,
+            requested_aap_capabilities: requestedAapCapabilities,
+        };
+        if (requestedTtlSecs !== undefined) {
+            params.requested_ttl_secs = requestedTtlSecs;
+        }
+        return this.rpc.call("tenzro_exchangeToken", params);
+    }
+    /**
+     * **RFC 7662 OAuth 2.0 Token Introspection.** Ask the AS whether a
+     * token is currently active and, if so, return its full claim set
+     * (RAR, AAP, cnf, controller_did, etc.). Per RFC 7662 §2.2 a failed
+     * validation returns `{ active: false }` with no other fields — the AS
+     * deliberately does not leak why the token is inactive.
+     *
+     * Use this from a downstream resource server that wants to validate a
+     * bearer token without re-implementing JWT signature checking.
+     */
+    async introspectToken(token) {
+        return this.rpc.call("tenzro_introspectToken", {
+            token,
+        });
+    }
+    /**
+     * **RFC 8414 / RFC 9728 OAuth Authorization Server / Protected Resource
+     * Metadata.** Returns the same metadata document the AS publishes at
+     * `GET /.well-known/openid-configuration`. Useful for JSON-RPC-only
+     * clients (CLI, agents) that don't want to also speak HTTP discovery.
+     */
+    async oauthDiscovery() {
+        return this.rpc.call("tenzro_oauthDiscovery", []);
+    }
+}
+exports.AuthClient = AuthClient;
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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