@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/tap-oidca.d.ts

@@ -0,0 +1,288 @@
+/**
+ * BOTCHA OIDC-A Attestation Module
+ *
+ * Implements OIDC-A (OpenID Connect for Agents) attestation:
+ *   - EAT (Entity Attestation Token) issuance per draft-ietf-rats-eat-25
+ *   - OIDC-A compatible claims per draft-aap-oauth-profile (Feb 2026)
+ *   - OAuth 2.0 AS metadata discovery per RFC 8414
+ *   - Agent Authorization Grant per draft-rosenberg-oauth-aauth
+ *   - OIDC-A UserInfo endpoint
+ *
+ * EAT tokens make BOTCHA an `agent_attestation` endpoint that enterprise
+ * auth servers embed in OpenID Connect for Agents token chains.
+ */
+import type { KVNamespace } from './auth.js';
+import type { ES256SigningKeyJWK } from './auth.js';
+/**
+ * EAT (Entity Attestation Token) payload — draft-ietf-rats-eat-25
+ *
+ * JSON-encoded EAT as a JWT (JOSE-protected).
+ * Claims follow Section 4 of draft-ietf-rats-eat-25:
+ *   - iat, exp, iss, sub: standard JWT claims (reused by EAT)
+ *   - eat_nonce: anti-replay nonce (Section 4.1)
+ *   - eat_profile: URI identifying the EAT profile (Section 4.3.2)
+ *   - ueid: Universal Entity ID (Section 4.2.1) — base64url(sha256(agent_id))
+ *   - oemid: Hardware OEM ID (Section 4.2.3) — for software agents, this is vendor
+ *   - swname: Software name (Section 4.2.6)
+ *   - swversion: Software version (Section 4.2.7)
+ *   - dbgstat: Debug status (Section 4.2.9)
+ *   - intuse: Intended use (Section 4.3.3)
+ *   - botcha_*: BOTCHA-specific private claims
+ */
+export interface EATPayload {
+    iss: string;
+    sub: string;
+    iat: number;
+    exp: number;
+    eat_profile: string;
+    eat_nonce: string;
+    ueid: string;
+    oemid: string;
+    swname: string;
+    swversion: string;
+    dbgstat: EATDebugStatus;
+    intuse: EATIntendedUse;
+    botcha_verified: true;
+    botcha_challenge_id: string;
+    botcha_solve_time_ms: number;
+    botcha_app_id?: string;
+    botcha_verification_method: 'speed-challenge' | 'hybrid-challenge' | 'reasoning-challenge';
+}
+/**
+ * EAT dbgstat values (Section 4.2.9 of draft-ietf-rats-eat-25)
+ */
+export type EATDebugStatus = 'Enabled' | 'Disabled' | 'Disabled-Since-Boot' | 'Disabled-Permanently' | 'Disabled-Fully-And-Permanently';
+/**
+ * EAT intuse values (Section 4.3.3 of draft-ietf-rats-eat-25)
+ */
+export type EATIntendedUse = 'generic' | 'registration' | 'provisioning' | 'csr' | 'pop';
+/**
+ * OIDC-A agent claims block — for embedding in enterprise ID tokens
+ *
+ * Based on:
+ *   - draft-aap-oauth-profile Section 5 (JWT Claim Schema for Agents)
+ *   - OIDC-A 1.0 agent extension claims
+ *
+ * Enterprise auth servers call /v1/attestation/oidc-agent-claims to enrich
+ * ID tokens with these claims before issuing them to clients.
+ */
+export interface OIDCAgentClaims {
+    agent_model: string;
+    agent_version?: string;
+    agent_capabilities: string[];
+    agent_attestation: string;
+    delegation_chain: string[];
+    agent_id: string;
+    agent_operator?: string;
+    agent_verification: {
+        method: string;
+        solve_time_ms: number;
+        verified_at: string;
+        issuer: string;
+        challenge_id: string;
+    };
+    human_oversight_required: boolean;
+    oversight_contact?: string;
+    task_id?: string;
+    task_purpose?: string;
+    iat: number;
+    exp: number;
+    iss: string;
+}
+/**
+ * Agent Grant result — output of POST /v1/auth/agent-grant
+ *
+ * Implements the "Agent Authorization Grant" from draft-rosenberg-oauth-aauth.
+ * An agent presents its BOTCHA token and receives a scoped OAuth-style grant.
+ */
+export interface AgentGrantResult {
+    grant_type: 'urn:ietf:params:oauth:grant-type:agent_authorization';
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    scope: string;
+    agent_id: string;
+    app_id?: string;
+    human_oversight_required: boolean;
+    oversight_status: 'none' | 'pending' | 'approved' | 'denied';
+    oversight_polling_url?: string;
+    agent_claims: OIDCAgentClaims;
+    eat_token: string;
+}
+/**
+ * Stored grant state for HITL polling
+ */
+export interface PendingGrant {
+    grant_id: string;
+    agent_id: string;
+    app_id?: string;
+    scope: string;
+    requested_at: number;
+    status: 'pending' | 'approved' | 'denied';
+    approved_at?: number;
+    denied_at?: number;
+    denial_reason?: string;
+}
+export declare const BOTCHA_EAT_PROFILE = "https://botcha.ai/eat-profile/v1";
+export declare const BOTCHA_ISSUER = "botcha.ai";
+export declare const EAT_TOKEN_TTL_SECONDS = 3600;
+export declare const OIDC_CLAIMS_TTL_SECONDS = 3600;
+export declare const AGENT_GRANT_TTL_SECONDS = 3600;
+/**
+ * Well-known BOTCHA agent capabilities
+ * Enterprise auth servers can use these to filter agents by capability.
+ */
+export declare const BOTCHA_AGENT_CAPABILITIES: string[];
+/**
+ * Issue an EAT (Entity Attestation Token) from a valid BOTCHA access token.
+ *
+ * The EAT proves:
+ * 1. The agent solved a computational challenge (proving it is a bot)
+ * 2. The challenge was issued by botcha.ai
+ * 3. The solution time demonstrates AI-speed computation
+ * 4. The agent is registered with a specific app
+ *
+ * This token can be embedded as `agent_attestation` in OIDC-A tokens.
+ *
+ * @param botchaPayload - Verified BOTCHA access token payload
+ * @param signingKey - ES256 private key for signing (required for EAT)
+ * @param options - Optional parameters
+ * @returns Signed EAT JWT
+ */
+export declare function issueEAT(botchaPayload: {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    type: 'botcha-verified';
+    solveTime: number;
+    app_id?: string;
+    aud?: string;
+}, signingKey: ES256SigningKeyJWK, options?: {
+    nonce?: string;
+    agentModel?: string;
+    ttlSeconds?: number;
+    verificationMethod?: 'speed-challenge' | 'hybrid-challenge' | 'reasoning-challenge';
+}): Promise<string>;
+/**
+ * Build OIDC-A compatible agent claims block.
+ *
+ * This is the full claims object that enterprise auth servers embed in their
+ * ID tokens for agent grants. It includes the EAT token as `agent_attestation`.
+ *
+ * @param botchaPayload - Verified BOTCHA access token payload
+ * @param eatToken - Signed EAT JWT (from issueEAT)
+ * @param signingKey - ES256 signing key
+ * @param options - Agent metadata and OIDC-A options
+ * @returns Signed OIDC-A claims JWT + plain claims object
+ */
+export declare function buildOIDCAgentClaims(botchaPayload: {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    type: 'botcha-verified';
+    solveTime: number;
+    app_id?: string;
+    aud?: string;
+}, eatToken: string, signingKey: ES256SigningKeyJWK, options?: {
+    agentModel?: string;
+    agentVersion?: string;
+    agentCapabilities?: string[];
+    agentOperator?: string;
+    delegationChain?: string[];
+    humanOversightRequired?: boolean;
+    oversightContact?: string;
+    taskId?: string;
+    taskPurpose?: string;
+    scope?: string;
+    ttlSeconds?: number;
+    verificationMethod?: 'speed-challenge' | 'hybrid-challenge' | 'reasoning-challenge';
+}): Promise<{
+    claims: OIDCAgentClaims;
+    claimsJwt: string;
+}>;
+/**
+ * Issue an Agent Authorization Grant.
+ *
+ * Implements draft-rosenberg-oauth-aauth "Agent Authorization Grant":
+ * - Agent presents BOTCHA access token as credential
+ * - Server issues a scoped grant JWT bound to the agent's identity
+ * - Optionally queued for human-in-the-loop approval
+ *
+ * Grant token is a signed JWT with AAP claims (draft-aap-oauth-profile §5).
+ *
+ * @param botchaPayload - Verified BOTCHA access token payload
+ * @param eatToken - EAT JWT from issueEAT
+ * @param oidcClaims - OIDC-A claims object from buildOIDCAgentClaims
+ * @param signingKey - ES256 signing key
+ * @param kv - KV namespace for storing pending grants (for HITL polling)
+ * @param options - Grant options
+ * @returns AgentGrantResult
+ */
+export declare function issueAgentGrant(botchaPayload: {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    type: 'botcha-verified';
+    solveTime: number;
+    app_id?: string;
+}, eatToken: string, oidcClaims: OIDCAgentClaims, signingKey: ES256SigningKeyJWK, kv: KVNamespace, baseUrl: string, options?: {
+    scope?: string;
+    humanOversightRequired?: boolean;
+    ttlSeconds?: number;
+    taskId?: string;
+    taskPurpose?: string;
+    constraints?: Record<string, unknown>;
+}): Promise<AgentGrantResult>;
+/**
+ * Build OAuth 2.0 Authorization Server metadata (RFC 8414).
+ *
+ * This makes BOTCHA discoverable as an OAuth AS by enterprise auth servers
+ * that implement RFC 8414 auto-configuration.
+ *
+ * Extended with OIDC-A specific metadata for agent auth servers.
+ */
+export declare function buildOAuthASMetadata(baseUrl: string): object;
+/**
+ * Verify and decode a BOTCHA EAT token.
+ * Used by the UserInfo endpoint to extract agent identity.
+ *
+ * @param eatJwt - The EAT JWT to verify
+ * @param publicKey - ES256 public key JWK
+ * @returns Verified EAT payload or null
+ */
+export declare function verifyEAT(eatJwt: string, publicKey: object): Promise<EATPayload | null>;
+/**
+ * Poll the status of a pending human-in-the-loop grant.
+ *
+ * @param grantId - The grant ID to poll
+ * @param kv - KV namespace
+ * @returns Current grant status or null if not found
+ */
+export declare function getGrantStatus(grantId: string, kv: KVNamespace): Promise<PendingGrant | null>;
+/**
+ * Approve or deny a pending agent grant (admin action).
+ *
+ * @param grantId - The grant ID
+ * @param decision - 'approved' or 'denied'
+ * @param reason - Optional denial reason
+ * @param kv - KV namespace
+ */
+export declare function resolveGrant(grantId: string, decision: 'approved' | 'denied', reason: string | undefined, kv: KVNamespace): Promise<{
+    success: boolean;
+    grant?: PendingGrant;
+    error?: string;
+}>;
+declare const _default: {
+    issueEAT: typeof issueEAT;
+    buildOIDCAgentClaims: typeof buildOIDCAgentClaims;
+    issueAgentGrant: typeof issueAgentGrant;
+    buildOAuthASMetadata: typeof buildOAuthASMetadata;
+    verifyEAT: typeof verifyEAT;
+    getGrantStatus: typeof getGrantStatus;
+    resolveGrant: typeof resolveGrant;
+};
+export default _default;
+//# sourceMappingURL=tap-oidca.d.ts.map

package/dist/tap-oidca.d.ts.map

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