@permission-protocol/sdk 0.1.0-alpha.3 → 0.1.0

package/dist/index.d.ts

@@ -1,297 +1,81 @@
-/**
- * HashablePayload v1 Implementation
- * Conforms to spec/hashable-payload-v1.md
- */
-/**
- * HashablePayload v1 - the canonical envelope for computing inputHash.
- * Matches spec/hashable-payload-v1.md exactly.
- */
-interface HashablePayloadV1 {
-    tool: string;
-    operation: string;
-    input: unknown;
-    metadata: Record<string, unknown> | null;
+declare const DEFAULT_BASE_URL = "https://app.permissionprotocol.com";
+interface SDKConfig {
+    apiKey: string;
+    baseUrl: string;
 }
-/**
- * Canonicalize any JSON value.
- *
- * Rules (from spec/hashable-payload-v1.md):
- * - null → "null"
- * - primitives → JSON.stringify(value)
- * - arrays → "[" + items.map(canonicalize).join(",") + "]"
- * - objects: sort keys lexicographically, omit undefined values
- */
-declare function canonicalize(obj: unknown): string;
-/**
- * Compute inputHash from HashablePayload v1.
- *
- * Algorithm (from spec/hashable-payload-v1.md):
- * 1. Canonicalize the payload
- * 2. SHA-256 hash (UTF-8 encoded)
- * 3. Lowercase hex encoding
- * 4. Prefix with "sha256:"
- */
-declare function computeHash(payload: HashablePayloadV1): string;
-/**
- * Build HashablePayload v1 from SDK execute options.
- */
-declare function buildHashablePayload(opts: {
-    tool: string;
-    operation: string;
-    input: unknown;
-    metadata?: Record<string, unknown>;
-}): HashablePayloadV1;
+declare function configure(apiKey?: string, baseUrl?: string): SDKConfig;
 
-/**
- * Permission Protocol SDK Types
- *
- * Public types for the SDK. Internal types are not exported.
- */
+declare class PermissionProtocolError extends Error {
+    constructor(message: string);
+}
+declare class PermissionDenied extends PermissionProtocolError {
+    constructor(message?: string);
+}
+declare class ApprovalTimeout extends PermissionProtocolError {
+    constructor(message?: string);
+}
 
-interface ConfigureOptions {
-    /**
-     * The Permission Protocol API endpoint.
-     * Example: 'https://api.permissionprotocol.com'
-     */
-    endpoint: string;
-    /**
-     * API key for authentication.
-     */
-    apiKey: string;
-    /**
-     * Request timeout in milliseconds.
-     * Default: 10000 (10 seconds)
-     */
-    timeoutMs?: number;
-    /**
-     * Protocol version to use.
-     * Default: 1
-     */
-    protocolVersion?: number;
-    /**
-     * SDK version string (sent in X-PP-SDK-Version header).
-     * Default: package.json version
-     */
-    sdkVersion?: string;
-    /**
-     * Optional receipt verification hook.
-     * Called after receiving a receipt from hosted PP.
-     * Return false to reject the receipt (throws INVALID_RECEIPT).
-     * Default: no-op (always returns true)
-     *
-     * Use this hook for future signature verification.
-     */
-    verifyReceipt?: (receipt: PermissionReceipt) => boolean | Promise<boolean>;
+type ReceiptStatus = "APPROVED" | "DENIED" | "PENDING" | "EXPIRED" | string;
+interface ReceiptData {
+    id: string;
+    status: ReceiptStatus;
+    action?: string;
+    resource?: string;
+    actor?: string;
+    approved_by?: string | null;
+    policy?: string | null;
+    signature?: string | null;
+    issuer?: string;
+    timestamp?: string;
+    expires_at?: string | null;
+    url?: string;
+    valid?: boolean;
+    [key: string]: unknown;
 }
-interface ExecuteOptions<TInput> {
-    /**
-     * Tenant/organization identifier.
-     */
-    tenantId: string;
-    /**
-     * Agent identifier making the request.
-     */
-    agentId: string;
-    /**
-     * Tool being invoked (e.g., 'wordpress', 'github', 'slack').
-     */
-    tool: string;
-    /**
-     * Operation on the tool (e.g., 'publish_post', 'create_pr').
-     */
-    operation: string;
-    /**
-     * Input payload for the operation.
-     * Can be any JSON-serializable value.
-     */
-    input: TInput;
-    /**
-     * Optional metadata for risk assessment.
-     * Included in the input hash.
-     */
+interface AuthorizeParams {
+    action: string;
+    resource: string;
+    actor?: string;
     metadata?: Record<string, unknown>;
-    /**
-     * Optional reversibility hint for risk assessment.
-     * Default: 'UNKNOWN' (no policy signal encoded by SDK)
-     */
-    reversibility?: 'REVERSIBLE' | 'PARTIALLY_REVERSIBLE' | 'IRREVERSIBLE' | 'UNKNOWN';
-    /**
-     * Execution mode.
-     * - 'hosted': Connect to hosted Permission Protocol (default)
-     * - 'dev': Local development mode with auto-approval
-     */
-    mode?: 'hosted' | 'dev';
+    wait?: boolean;
+    timeout?: number;
 }
-type ExecuteResult<TResult> = {
-    status: 'APPROVED';
-    receipt: PermissionReceipt;
-    result?: TResult;
-} | {
-    status: 'REQUIRES_APPROVAL';
-    receipt: PermissionReceipt;
-} | {
-    status: 'DENIED';
-    receipt: PermissionReceipt;
-};
-interface PermissionReceipt {
-    /**
-     * Unique receipt identifier.
-     */
-    receiptId: string;
-    /**
-     * Tenant/organization identifier.
-     */
-    tenantId: string;
-    /**
-     * Agent that requested authorization.
-     */
-    agentId: string;
-    /**
-     * Tool that was requested.
-     */
-    tool: string;
-    /**
-     * Operation that was requested.
-     */
-    operation: string;
-    /**
-     * SHA-256 hash of the canonical input payload.
-     * Format: 'sha256:<hex>'
-     */
-    inputHash: string;
-    /**
-     * The decision from Permission Protocol.
-     */
-    decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL';
-    /**
-     * Reason codes explaining the decision.
-     * May include: REQUIRES_FOUNDER_VETO, APPROVAL_EXPIRED, EXECUTION_ERROR, etc.
-     */
-    reasonCodes: string[];
-    /**
-     * Who approved the action.
-     * - 'policy': Auto-approved by policy
-     * - 'human': Approved by a human
-     * - 'founder': Approved by founder
-     * - 'dev_mock': Dev mode auto-approval (NOT valid for production)
-     */
-    approver: 'policy' | 'human' | 'founder' | 'dev_mock';
-    /**
-     * Policy version that made the decision (if available).
-     */
-    policyVersion?: string;
-    /**
-     * When the receipt was created (ISO 8601).
-     */
-    createdAt: string;
-    /**
-     * Receipt signature (future-proof placeholder).
-     * Used for verifying receipt authenticity.
-     */
-    receiptSig?: string;
-    /**
-     * Signature algorithm used (future-proof placeholder).
-     */
-    sigAlg?: 'ed25519' | 'hmac-sha256';
+interface VerifyResponse {
+    valid: boolean;
+    receipt?: ReceiptData;
+    [key: string]: unknown;
 }
 
-/**
- * PermissionRouter - Main SDK Entry Point
- *
- * The only two methods developers need:
- * - PermissionRouter.configure(opts) - Configure the client
- * - PermissionRouter.execute(opts) - Request authorization
- *
- * This SDK does NOT:
- * - Make decisions
- * - Execute tools
- * - Store receipts
- * - Implement policy logic
- */
-
-/**
- * Permission Protocol SDK
- *
- * Standardized authorization for AI agents.
- *
- * @example
- * ```typescript
- * import { PermissionRouter } from '@permission-protocol/sdk';
- *
- * // Configure once
- * PermissionRouter.configure({
- *   endpoint: 'https://api.permissionprotocol.com',
- *   apiKey: process.env.PP_API_KEY!,
- * });
- *
- * // Request authorization
- * const decision = await PermissionRouter.execute({
- *   tenantId: 'acme',
- *   agentId: 'seo-agent',
- *   tool: 'wordpress',
- *   operation: 'publish_post',
- *   input: postPayload,
- * });
- *
- * if (decision.status !== 'APPROVED') {
- *   // Handle denial or pending approval
- *   process.exit(2);
- * }
- *
- * // Tool execution happens elsewhere - SDK does NOT execute tools
- * ```
- */
-declare const PermissionRouter: {
-    /**
-     * Configure the Permission Protocol client.
-     *
-     * Must be called before execute() in hosted mode.
-     *
-     * @param opts - Configuration options
-     */
-    configure(opts: ConfigureOptions): void;
-    /**
-     * Request authorization for an action.
-     *
-     * Returns a decision + receipt. Does NOT execute the action.
-     *
-     * @param opts - Execute options
-     * @returns Promise resolving to decision (APPROVED, REQUIRES_APPROVAL, or DENIED) with receipt
-     * @throws PermissionProtocolError on network failure, timeout, or invalid response
-     */
-    execute<TInput, TResult = unknown>(opts: ExecuteOptions<TInput>): Promise<ExecuteResult<TResult>>;
-    /**
-     * Check if the client is configured.
-     * Useful for testing and debugging.
-     */
-    isConfigured(): boolean;
-    /**
-     * Reset configuration (for testing).
-     * @internal
-     */
-    _reset(): void;
-};
+declare class Receipt {
+    readonly id: string;
+    readonly status: ReceiptStatus;
+    readonly action?: string;
+    readonly resource?: string;
+    readonly actor?: string;
+    readonly approvedBy?: string | null;
+    readonly policy?: string | null;
+    readonly signature?: string | null;
+    readonly issuer?: string;
+    readonly timestamp?: string;
+    readonly expiresAt?: string | null;
+    readonly url?: string;
+    private readonly payload;
+    private readonly isValid;
+    constructor(payload: ReceiptData);
+    get valid(): boolean;
+    json(): ReceiptData;
+}
 
-/**
- * Permission Protocol SDK Errors
- *
- * Fail-closed error handling. No silent success.
- */
-/**
- * Error codes for Permission Protocol errors.
- */
-type ErrorCode = 'EXECUTION_UNAUTHORIZED' | 'INVALID_RECEIPT' | 'MISCONFIGURED';
-/**
- * Error thrown by Permission Protocol SDK.
- *
- * The SDK fails closed on all errors - there is no silent success path.
- */
-declare class PermissionProtocolError extends Error {
-    /**
-     * Error code for programmatic handling.
-     */
-    readonly code: ErrorCode;
-    constructor(code: ErrorCode, message: string);
+declare function authorize(action: string, resource: string, actor?: string, metadata?: Record<string, unknown>, wait?: boolean, timeout?: number): Promise<Receipt>;
+declare function verify(receiptId: string): Promise<Receipt>;
+interface RequireApprovalOptions {
+    action?: string;
+    resource: string;
+    actor?: string;
+    metadata?: Record<string, unknown>;
+    wait?: boolean;
+    timeout?: number;
 }
+declare function requireApproval(options: RequireApprovalOptions): <TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult | Promise<TResult>) => (...args: TArgs) => Promise<TResult>;
 
-export { type ConfigureOptions, type ErrorCode, type ExecuteOptions, type ExecuteResult, type HashablePayloadV1, PermissionProtocolError, type PermissionReceipt, PermissionRouter, buildHashablePayload, canonicalize, computeHash };
+export { ApprovalTimeout, type AuthorizeParams, DEFAULT_BASE_URL, PermissionDenied, PermissionProtocolError, Receipt, type ReceiptData, type ReceiptStatus, type RequireApprovalOptions, type SDKConfig, type VerifyResponse, authorize, configure, requireApproval, verify };