@permission-protocol/sdk 0.1.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,297 @@
+/**
+ * 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;
+}
+/**
+ * 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;
+
+/**
+ * Permission Protocol SDK Types
+ *
+ * Public types for the SDK. Internal types are not exported.
+ */
+
+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>;
+}
+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.
+     */
+    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';
+}
+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';
+}
+
+/**
+ * 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;
+};
+
+/**
+ * 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);
+}
+
+export { type ConfigureOptions, type ErrorCode, type ExecuteOptions, type ExecuteResult, type HashablePayloadV1, PermissionProtocolError, type PermissionReceipt, PermissionRouter, buildHashablePayload, canonicalize, computeHash };

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/**
+ * 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;
+}
+/**
+ * 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;
+
+/**
+ * Permission Protocol SDK Types
+ *
+ * Public types for the SDK. Internal types are not exported.
+ */
+
+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>;
+}
+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.
+     */
+    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';
+}
+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';
+}
+
+/**
+ * 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;
+};
+
+/**
+ * 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);
+}
+
+export { type ConfigureOptions, type ErrorCode, type ExecuteOptions, type ExecuteResult, type HashablePayloadV1, PermissionProtocolError, type PermissionReceipt, PermissionRouter, buildHashablePayload, canonicalize, computeHash };

package/dist/index.js

@@ -0,0 +1,356 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PermissionProtocolError: () => PermissionProtocolError,
+  PermissionRouter: () => PermissionRouter,
+  buildHashablePayload: () => buildHashablePayload,
+  canonicalize: () => canonicalize,
+  computeHash: () => computeHash
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hash.ts
+var import_crypto = require("crypto");
+function canonicalize(obj) {
+  if (obj === null) {
+    return "null";
+  }
+  if (typeof obj !== "object") {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return "[" + obj.map(canonicalize).join(",") + "]";
+  }
+  const record = obj;
+  const sorted = Object.keys(record).filter((k) => record[k] !== void 0).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(record[k])}`);
+  return "{" + sorted.join(",") + "}";
+}
+function computeHash(payload) {
+  const canonical = canonicalize(payload);
+  const hash = (0, import_crypto.createHash)("sha256").update(canonical, "utf8").digest("hex");
+  return `sha256:${hash}`;
+}
+function buildHashablePayload(opts) {
+  return {
+    tool: opts.tool,
+    operation: opts.operation,
+    input: opts.input,
+    metadata: opts.metadata ?? null
+  };
+}
+
+// src/devApprovalMock.ts
+function devApprovalMock(opts) {
+  console.warn(
+    '\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551           PERMISSION PROTOCOL - DEV MODE                     \u2551\n\u2551                                                              \u2551\n\u2551   This approval is NOT valid for production.                 \u2551\n\u2551   Real enforcement requires hosted Permission Protocol.      \u2551\n\u2551                                                              \u2551\n\u2551   Set mode: "hosted" for production use.                     \u2551\n\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n'
+  );
+  const hashablePayload = buildHashablePayload(opts);
+  const inputHash = computeHash(hashablePayload);
+  const receipt = {
+    receiptId: `dev_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`,
+    tenantId: opts.tenantId,
+    agentId: opts.agentId,
+    tool: opts.tool,
+    operation: opts.operation,
+    inputHash,
+    decision: "APPROVED",
+    reasonCodes: ["DEV_MODE_APPROVAL"],
+    approver: "dev_mock",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    status: "APPROVED",
+    receipt
+  };
+}
+
+// src/errors.ts
+var PermissionProtocolError = class _PermissionProtocolError extends Error {
+  /**
+   * Error code for programmatic handling.
+   */
+  code;
+  constructor(code, message) {
+    super(`[PermissionProtocol:${code}] ${message}`);
+    this.name = "PermissionProtocolError";
+    this.code = code;
+    Object.setPrototypeOf(this, _PermissionProtocolError.prototype);
+  }
+};
+
+// src/mapping.ts
+function mapHostedResponse(hosted, _opts) {
+  if (!hosted.receipt || !hosted.hostedStatus) {
+    throw new PermissionProtocolError(
+      "INVALID_RECEIPT",
+      "Hosted response missing required fields (receipt or hostedStatus)"
+    );
+  }
+  if (!hosted.receipt.receiptId) {
+    throw new PermissionProtocolError(
+      "INVALID_RECEIPT",
+      "Hosted response receipt missing receiptId"
+    );
+  }
+  return mapStatus(hosted.hostedStatus, hosted.receipt, hosted.result);
+}
+function mapStatus(status, receipt, result) {
+  switch (status) {
+    // === APPROVED ===
+    case "APPROVED":
+      return {
+        status: "APPROVED",
+        receipt: { ...receipt, decision: "APPROVED" },
+        result
+      };
+    // === REQUIRES_APPROVAL (direct) ===
+    case "REQUIRES_APPROVAL":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: { ...receipt, decision: "REQUIRES_APPROVAL" }
+      };
+    // === REQUIRES_FOUNDER_VETO -> REQUIRES_APPROVAL + reason code ===
+    case "REQUIRES_FOUNDER_VETO":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: {
+          ...receipt,
+          decision: "REQUIRES_APPROVAL",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "REQUIRES_FOUNDER_VETO")
+        }
+      };
+    // === EXECUTING -> REQUIRES_APPROVAL + reason code ===
+    case "EXECUTING":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: {
+          ...receipt,
+          decision: "REQUIRES_APPROVAL",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "EXECUTING_PENDING_RESULT")
+        }
+      };
+    // === PENDING_DECISION -> REQUIRES_APPROVAL + reason code ===
+    case "PENDING_DECISION":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: {
+          ...receipt,
+          decision: "REQUIRES_APPROVAL",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "PENDING_DECISION")
+        }
+      };
+    // === DENIED (direct) ===
+    case "DENIED":
+      return {
+        status: "DENIED",
+        receipt: { ...receipt, decision: "DENIED" }
+      };
+    // === EXPIRED -> DENIED + reason code ===
+    case "EXPIRED":
+      return {
+        status: "DENIED",
+        receipt: {
+          ...receipt,
+          decision: "DENIED",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "APPROVAL_EXPIRED")
+        }
+      };
+    // === ERROR -> DENIED + reason code ===
+    case "ERROR":
+      return {
+        status: "DENIED",
+        receipt: {
+          ...receipt,
+          decision: "DENIED",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "EXECUTION_ERROR")
+        }
+      };
+    // === Unknown status -> fail closed ===
+    default:
+      throw new PermissionProtocolError(
+        "EXECUTION_UNAUTHORIZED",
+        `Unknown status from Permission Protocol: ${status}`
+      );
+  }
+}
+function ensureReasonCode(codes, code) {
+  if (codes.includes(code)) {
+    return codes;
+  }
+  return [...codes, code];
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_SDK_VERSION = "0.1.0-alpha.1";
+var DEFAULT_PROTOCOL_VERSION = 1;
+async function fetchHostedPP(opts, body, headers) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const sdkVersion = opts.sdkVersion ?? DEFAULT_SDK_VERSION;
+  const protocolVersion = opts.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${opts.endpoint}/api/permission/v1/execute`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${opts.apiKey}`,
+        "X-PP-SDK-Version": sdkVersion,
+        "X-PP-Protocol-Version": String(protocolVersion),
+        "X-PP-Tenant-Id": headers.tenantId,
+        "X-PP-Agent-Id": headers.agentId
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      throw new PermissionProtocolError(
+        "EXECUTION_UNAUTHORIZED",
+        `Permission Protocol returned ${response.status}`
+      );
+    }
+    let hosted;
+    try {
+      hosted = await response.json();
+    } catch {
+      throw new PermissionProtocolError(
+        "EXECUTION_UNAUTHORIZED",
+        "Permission Protocol returned malformed response"
+      );
+    }
+    return hosted;
+  } catch (err) {
+    clearTimeout(timeoutId);
+    if (err instanceof PermissionProtocolError) {
+      throw err;
+    }
+    const error = err;
+    const message = error.name === "AbortError" ? "Permission Protocol request timed out" : "Permission Protocol unreachable";
+    throw new PermissionProtocolError("EXECUTION_UNAUTHORIZED", message);
+  }
+}
+
+// src/router.ts
+var config = null;
+var PermissionRouter = {
+  /**
+   * Configure the Permission Protocol client.
+   * 
+   * Must be called before execute() in hosted mode.
+   * 
+   * @param opts - Configuration options
+   */
+  configure(opts) {
+    config = opts;
+  },
+  /**
+   * 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
+   */
+  async execute(opts) {
+    if (opts.mode === "dev") {
+      return devApprovalMock(opts);
+    }
+    if (!config) {
+      throw new PermissionProtocolError(
+        "MISCONFIGURED",
+        "Permission Protocol client not configured. Call PermissionRouter.configure() first."
+      );
+    }
+    const hashablePayload = buildHashablePayload(opts);
+    const inputHash = computeHash(hashablePayload);
+    const body = {
+      tenantId: opts.tenantId,
+      actor: { agentId: opts.agentId },
+      intent: {
+        name: `${opts.tool}:${opts.operation}`,
+        summary: `${opts.tool} ${opts.operation}`,
+        category: opts.tool
+      },
+      action: {
+        tool: opts.tool,
+        operation: opts.operation,
+        parameters: opts.input
+      },
+      context: {
+        environment: "production",
+        reversibility: opts.reversibility ?? "UNKNOWN",
+        metadata: opts.metadata
+      },
+      hashes: { inputHash }
+    };
+    const hosted = await fetchHostedPP(
+      {
+        endpoint: config.endpoint,
+        apiKey: config.apiKey,
+        timeoutMs: config.timeoutMs,
+        protocolVersion: config.protocolVersion,
+        sdkVersion: config.sdkVersion
+      },
+      body,
+      {
+        tenantId: opts.tenantId,
+        agentId: opts.agentId
+      }
+    );
+    const result = mapHostedResponse(hosted, opts);
+    if (config.verifyReceipt) {
+      const valid = await config.verifyReceipt(result.receipt);
+      if (!valid) {
+        throw new PermissionProtocolError(
+          "INVALID_RECEIPT",
+          "Receipt verification failed"
+        );
+      }
+    }
+    return result;
+  },
+  /**
+   * Check if the client is configured.
+   * Useful for testing and debugging.
+   */
+  isConfigured() {
+    return config !== null;
+  },
+  /**
+   * Reset configuration (for testing).
+   * @internal
+   */
+  _reset() {
+    config = null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PermissionProtocolError,
+  PermissionRouter,
+  buildHashablePayload,
+  canonicalize,
+  computeHash
+});

package/dist/index.mjs

@@ -0,0 +1,325 @@
+// src/hash.ts
+import { createHash } from "crypto";
+function canonicalize(obj) {
+  if (obj === null) {
+    return "null";
+  }
+  if (typeof obj !== "object") {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return "[" + obj.map(canonicalize).join(",") + "]";
+  }
+  const record = obj;
+  const sorted = Object.keys(record).filter((k) => record[k] !== void 0).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(record[k])}`);
+  return "{" + sorted.join(",") + "}";
+}
+function computeHash(payload) {
+  const canonical = canonicalize(payload);
+  const hash = createHash("sha256").update(canonical, "utf8").digest("hex");
+  return `sha256:${hash}`;
+}
+function buildHashablePayload(opts) {
+  return {
+    tool: opts.tool,
+    operation: opts.operation,
+    input: opts.input,
+    metadata: opts.metadata ?? null
+  };
+}
+
+// src/devApprovalMock.ts
+function devApprovalMock(opts) {
+  console.warn(
+    '\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551           PERMISSION PROTOCOL - DEV MODE                     \u2551\n\u2551                                                              \u2551\n\u2551   This approval is NOT valid for production.                 \u2551\n\u2551   Real enforcement requires hosted Permission Protocol.      \u2551\n\u2551                                                              \u2551\n\u2551   Set mode: "hosted" for production use.                     \u2551\n\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n'
+  );
+  const hashablePayload = buildHashablePayload(opts);
+  const inputHash = computeHash(hashablePayload);
+  const receipt = {
+    receiptId: `dev_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`,
+    tenantId: opts.tenantId,
+    agentId: opts.agentId,
+    tool: opts.tool,
+    operation: opts.operation,
+    inputHash,
+    decision: "APPROVED",
+    reasonCodes: ["DEV_MODE_APPROVAL"],
+    approver: "dev_mock",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    status: "APPROVED",
+    receipt
+  };
+}
+
+// src/errors.ts
+var PermissionProtocolError = class _PermissionProtocolError extends Error {
+  /**
+   * Error code for programmatic handling.
+   */
+  code;
+  constructor(code, message) {
+    super(`[PermissionProtocol:${code}] ${message}`);
+    this.name = "PermissionProtocolError";
+    this.code = code;
+    Object.setPrototypeOf(this, _PermissionProtocolError.prototype);
+  }
+};
+
+// src/mapping.ts
+function mapHostedResponse(hosted, _opts) {
+  if (!hosted.receipt || !hosted.hostedStatus) {
+    throw new PermissionProtocolError(
+      "INVALID_RECEIPT",
+      "Hosted response missing required fields (receipt or hostedStatus)"
+    );
+  }
+  if (!hosted.receipt.receiptId) {
+    throw new PermissionProtocolError(
+      "INVALID_RECEIPT",
+      "Hosted response receipt missing receiptId"
+    );
+  }
+  return mapStatus(hosted.hostedStatus, hosted.receipt, hosted.result);
+}
+function mapStatus(status, receipt, result) {
+  switch (status) {
+    // === APPROVED ===
+    case "APPROVED":
+      return {
+        status: "APPROVED",
+        receipt: { ...receipt, decision: "APPROVED" },
+        result
+      };
+    // === REQUIRES_APPROVAL (direct) ===
+    case "REQUIRES_APPROVAL":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: { ...receipt, decision: "REQUIRES_APPROVAL" }
+      };
+    // === REQUIRES_FOUNDER_VETO -> REQUIRES_APPROVAL + reason code ===
+    case "REQUIRES_FOUNDER_VETO":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: {
+          ...receipt,
+          decision: "REQUIRES_APPROVAL",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "REQUIRES_FOUNDER_VETO")
+        }
+      };
+    // === EXECUTING -> REQUIRES_APPROVAL + reason code ===
+    case "EXECUTING":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: {
+          ...receipt,
+          decision: "REQUIRES_APPROVAL",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "EXECUTING_PENDING_RESULT")
+        }
+      };
+    // === PENDING_DECISION -> REQUIRES_APPROVAL + reason code ===
+    case "PENDING_DECISION":
+      return {
+        status: "REQUIRES_APPROVAL",
+        receipt: {
+          ...receipt,
+          decision: "REQUIRES_APPROVAL",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "PENDING_DECISION")
+        }
+      };
+    // === DENIED (direct) ===
+    case "DENIED":
+      return {
+        status: "DENIED",
+        receipt: { ...receipt, decision: "DENIED" }
+      };
+    // === EXPIRED -> DENIED + reason code ===
+    case "EXPIRED":
+      return {
+        status: "DENIED",
+        receipt: {
+          ...receipt,
+          decision: "DENIED",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "APPROVAL_EXPIRED")
+        }
+      };
+    // === ERROR -> DENIED + reason code ===
+    case "ERROR":
+      return {
+        status: "DENIED",
+        receipt: {
+          ...receipt,
+          decision: "DENIED",
+          reasonCodes: ensureReasonCode(receipt.reasonCodes, "EXECUTION_ERROR")
+        }
+      };
+    // === Unknown status -> fail closed ===
+    default:
+      throw new PermissionProtocolError(
+        "EXECUTION_UNAUTHORIZED",
+        `Unknown status from Permission Protocol: ${status}`
+      );
+  }
+}
+function ensureReasonCode(codes, code) {
+  if (codes.includes(code)) {
+    return codes;
+  }
+  return [...codes, code];
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_SDK_VERSION = "0.1.0-alpha.1";
+var DEFAULT_PROTOCOL_VERSION = 1;
+async function fetchHostedPP(opts, body, headers) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const sdkVersion = opts.sdkVersion ?? DEFAULT_SDK_VERSION;
+  const protocolVersion = opts.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${opts.endpoint}/api/permission/v1/execute`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${opts.apiKey}`,
+        "X-PP-SDK-Version": sdkVersion,
+        "X-PP-Protocol-Version": String(protocolVersion),
+        "X-PP-Tenant-Id": headers.tenantId,
+        "X-PP-Agent-Id": headers.agentId
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      throw new PermissionProtocolError(
+        "EXECUTION_UNAUTHORIZED",
+        `Permission Protocol returned ${response.status}`
+      );
+    }
+    let hosted;
+    try {
+      hosted = await response.json();
+    } catch {
+      throw new PermissionProtocolError(
+        "EXECUTION_UNAUTHORIZED",
+        "Permission Protocol returned malformed response"
+      );
+    }
+    return hosted;
+  } catch (err) {
+    clearTimeout(timeoutId);
+    if (err instanceof PermissionProtocolError) {
+      throw err;
+    }
+    const error = err;
+    const message = error.name === "AbortError" ? "Permission Protocol request timed out" : "Permission Protocol unreachable";
+    throw new PermissionProtocolError("EXECUTION_UNAUTHORIZED", message);
+  }
+}
+
+// src/router.ts
+var config = null;
+var PermissionRouter = {
+  /**
+   * Configure the Permission Protocol client.
+   * 
+   * Must be called before execute() in hosted mode.
+   * 
+   * @param opts - Configuration options
+   */
+  configure(opts) {
+    config = opts;
+  },
+  /**
+   * 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
+   */
+  async execute(opts) {
+    if (opts.mode === "dev") {
+      return devApprovalMock(opts);
+    }
+    if (!config) {
+      throw new PermissionProtocolError(
+        "MISCONFIGURED",
+        "Permission Protocol client not configured. Call PermissionRouter.configure() first."
+      );
+    }
+    const hashablePayload = buildHashablePayload(opts);
+    const inputHash = computeHash(hashablePayload);
+    const body = {
+      tenantId: opts.tenantId,
+      actor: { agentId: opts.agentId },
+      intent: {
+        name: `${opts.tool}:${opts.operation}`,
+        summary: `${opts.tool} ${opts.operation}`,
+        category: opts.tool
+      },
+      action: {
+        tool: opts.tool,
+        operation: opts.operation,
+        parameters: opts.input
+      },
+      context: {
+        environment: "production",
+        reversibility: opts.reversibility ?? "UNKNOWN",
+        metadata: opts.metadata
+      },
+      hashes: { inputHash }
+    };
+    const hosted = await fetchHostedPP(
+      {
+        endpoint: config.endpoint,
+        apiKey: config.apiKey,
+        timeoutMs: config.timeoutMs,
+        protocolVersion: config.protocolVersion,
+        sdkVersion: config.sdkVersion
+      },
+      body,
+      {
+        tenantId: opts.tenantId,
+        agentId: opts.agentId
+      }
+    );
+    const result = mapHostedResponse(hosted, opts);
+    if (config.verifyReceipt) {
+      const valid = await config.verifyReceipt(result.receipt);
+      if (!valid) {
+        throw new PermissionProtocolError(
+          "INVALID_RECEIPT",
+          "Receipt verification failed"
+        );
+      }
+    }
+    return result;
+  },
+  /**
+   * Check if the client is configured.
+   * Useful for testing and debugging.
+   */
+  isConfigured() {
+    return config !== null;
+  },
+  /**
+   * Reset configuration (for testing).
+   * @internal
+   */
+  _reset() {
+    config = null;
+  }
+};
+export {
+  PermissionProtocolError,
+  PermissionRouter,
+  buildHashablePayload,
+  canonicalize,
+  computeHash
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@permission-protocol/sdk",
+  "version": "0.1.0-alpha.1",
+  "description": "Standardized authorization and receipts for autonomous AI actions",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/permission-protocol/permission-protocol",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/permission-protocol/permission-protocol"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "authorization",
+    "receipts",
+    "audit",
+    "human-in-the-loop",
+    "ci",
+    "governance"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:golden": "vitest run -t 'HashablePayload v1 conformance'",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}