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

package/dist/index.js

@@ -1,356 +1,239 @@
-"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 });
+// src/exceptions.ts
+var PermissionProtocolError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PermissionProtocolError";
   }
-  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";
+var PermissionDenied = class extends PermissionProtocolError {
+  constructor(message = "Permission was denied.") {
+    super(message);
+    this.name = "PermissionDenied";
   }
-  if (typeof obj !== "object") {
-    return JSON.stringify(obj);
-  }
-  if (Array.isArray(obj)) {
-    return "[" + obj.map(canonicalize).join(",") + "]";
+};
+var ApprovalTimeout = class extends PermissionProtocolError {
+  constructor(message = "Approval request timed out.") {
+    super(message);
+    this.name = "ApprovalTimeout";
   }
-  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}`;
+};
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://app.permissionprotocol.com";
+var configuredApiKey;
+var configuredBaseUrl;
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "");
 }
-function buildHashablePayload(opts) {
+function configure(apiKey, baseUrl) {
+  const resolvedApiKey = apiKey ?? process.env.PP_API_KEY;
+  const resolvedBaseUrl = baseUrl ?? process.env.PP_BASE_URL ?? DEFAULT_BASE_URL;
+  if (!resolvedApiKey) {
+    throw new PermissionProtocolError("Permission Protocol API key is required.");
+  }
+  configuredApiKey = resolvedApiKey;
+  configuredBaseUrl = normalizeBaseUrl(resolvedBaseUrl);
   return {
-    tool: opts.tool,
-    operation: opts.operation,
-    input: opts.input,
-    metadata: opts.metadata ?? null
+    apiKey: configuredApiKey,
+    baseUrl: configuredBaseUrl
   };
 }
-
-// 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()
-  };
+function getConfig() {
+  const apiKey = configuredApiKey ?? process.env.PP_API_KEY;
+  const baseUrl = configuredBaseUrl ?? process.env.PP_BASE_URL ?? DEFAULT_BASE_URL;
+  if (!apiKey) {
+    throw new PermissionProtocolError(
+      "Permission Protocol API key is not configured. Call configure(apiKey) or set PP_API_KEY."
+    );
+  }
   return {
-    status: "APPROVED",
-    receipt
+    apiKey,
+    baseUrl: normalizeBaseUrl(baseUrl)
   };
 }
 
-// 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/receipt.ts
+var Receipt = class {
+  constructor(payload) {
+    this.payload = { ...payload };
+    this.id = payload.id;
+    this.status = payload.status;
+    this.action = payload.action;
+    this.resource = payload.resource;
+    this.actor = payload.actor;
+    this.approvedBy = payload.approved_by;
+    this.policy = payload.policy;
+    this.signature = payload.signature;
+    this.issuer = payload.issuer;
+    this.timestamp = payload.timestamp;
+    this.expiresAt = payload.expires_at;
+    this.url = payload.url;
+    this.isValid = Boolean(payload.valid);
+  }
+  get valid() {
+    return this.isValid;
+  }
+  json() {
+    return { ...this.payload, valid: this.isValid };
   }
 };
 
-// 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)"
-    );
+// src/sdk.ts
+import { hostname } from "os";
+
+// src/client.ts
+function createHeaders(apiKey) {
+  return {
+    "Content-Type": "application/json",
+    "X-PP-API-Key": apiKey
+  };
+}
+function getErrorMessage(status, fallback, body) {
+  if (body && typeof body === "object") {
+    const maybeErr = body;
+    if (maybeErr.error && typeof maybeErr.error === "string") {
+      return maybeErr.error;
+    }
+    if (maybeErr.message && typeof maybeErr.message === "string") {
+      return maybeErr.message;
+    }
+  }
+  return `${fallback} (HTTP ${status})`;
+}
+async function postAuthorize(payload) {
+  const { apiKey, baseUrl } = getConfig();
+  const response = await fetch(`${baseUrl}/api/v1/receipts/verify`, {
+    method: "POST",
+    headers: createHeaders(apiKey),
+    body: JSON.stringify({
+      scope: payload,
+      failOnMissing: true
+    })
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new PermissionProtocolError(getErrorMessage(response.status, "Authorization failed", body));
   }
-  if (!hosted.receipt.receiptId) {
+  return body;
+}
+async function getReceipt(receiptId) {
+  const { apiKey, baseUrl } = getConfig();
+  const response = await fetch(`${baseUrl}/api/v1/receipts/${encodeURIComponent(receiptId)}`, {
+    method: "GET",
+    headers: createHeaders(apiKey)
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
     throw new PermissionProtocolError(
-      "INVALID_RECEIPT",
-      "Hosted response receipt missing receiptId"
+      getErrorMessage(response.status, `Failed to fetch receipt ${receiptId}`, body)
     );
   }
-  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}`
-      );
+  if (body && typeof body === "object" && "receipt" in body) {
+    return body.receipt;
   }
+  return body;
 }
-function ensureReasonCode(codes, code) {
-  if (codes.includes(code)) {
-    return codes;
+async function postVerify(receiptId) {
+  const { apiKey, baseUrl } = getConfig();
+  const response = await fetch(`${baseUrl}/api/v1/receipts/verify`, {
+    method: "POST",
+    headers: createHeaders(apiKey),
+    body: JSON.stringify({
+      receiptId
+    })
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new PermissionProtocolError(getErrorMessage(response.status, "Verification failed", body));
   }
-  return [...codes, code];
+  return body;
 }
 
-// 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"
-      );
+// src/sdk.ts
+var DEFAULT_TIMEOUT_SECONDS = 300;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var MAX_POLL_INTERVAL_MS = 1e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function asReceipt(data, fallbackId) {
+  if (!data?.id && !fallbackId) {
+    throw new PermissionProtocolError("Missing receipt data in API response.");
+  }
+  return new Receipt({
+    id: data?.id ?? fallbackId ?? "",
+    status: data?.status ?? "PENDING",
+    ...data
+  });
+}
+async function authorize(action, resource, actor, metadata, wait = true, timeout = DEFAULT_TIMEOUT_SECONDS) {
+  const params = { action, resource, actor, metadata, wait, timeout };
+  const resolvedActor = params.actor ?? hostname();
+  const response = await postAuthorize({
+    action: params.action,
+    resource: params.resource,
+    actor: resolvedActor,
+    metadata: params.metadata
+  });
+  const receipt = asReceipt(response.receipt, response.requestId);
+  if (response.approvalUrl) {
+    console.log(`Approval URL: ${response.approvalUrl}`);
+  }
+  if (!params.wait) {
+    return receipt;
+  }
+  const timeoutMs = Math.max(1, params.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1e3;
+  const deadline = Date.now() + timeoutMs;
+  let pollInterval = DEFAULT_POLL_INTERVAL_MS;
+  while (Date.now() < deadline) {
+    const current = await getReceipt(receipt.id);
+    const currentReceipt = asReceipt(current, receipt.id);
+    if (currentReceipt.status === "APPROVED") {
+      return currentReceipt;
     }
-    return hosted;
-  } catch (err) {
-    clearTimeout(timeoutId);
-    if (err instanceof PermissionProtocolError) {
-      throw err;
+    if (currentReceipt.status === "DENIED" || currentReceipt.status === "EXPIRED") {
+      throw new PermissionDenied(`Approval request ${receipt.id} ended with status ${currentReceipt.status}.`);
     }
-    const error = err;
-    const message = error.name === "AbortError" ? "Permission Protocol request timed out" : "Permission Protocol unreachable";
-    throw new PermissionProtocolError("EXECUTION_UNAUTHORIZED", message);
+    await sleep(pollInterval);
+    pollInterval = Math.min(MAX_POLL_INTERVAL_MS, Math.floor(pollInterval * 1.5));
   }
+  throw new ApprovalTimeout(
+    `Approval request ${receipt.id} was not approved within ${Math.floor(timeoutMs / 1e3)} seconds.`
+  );
 }
-
-// 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."
+async function verify(receiptId) {
+  const result = await postVerify(receiptId);
+  const payload = result.receipt ?? { id: receiptId, status: "PENDING" };
+  return new Receipt({
+    ...payload,
+    id: payload.id ?? receiptId,
+    valid: Boolean(result.valid)
+  });
+}
+function requireApproval(options) {
+  return function withApproval(fn) {
+    return async (...args) => {
+      const action = options.action ?? fn.name ?? "action";
+      await authorize(
+        action,
+        options.resource,
+        options.actor,
+        options.metadata,
+        options.wait ?? true,
+        options.timeout ?? DEFAULT_TIMEOUT_SECONDS
       );
-    }
-    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 }
+      return fn(...args);
     };
-    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 = {
+  };
+}
+export {
+  ApprovalTimeout,
+  DEFAULT_BASE_URL,
+  PermissionDenied,
   PermissionProtocolError,
-  PermissionRouter,
-  buildHashablePayload,
-  canonicalize,
-  computeHash
-});
+  Receipt,
+  authorize,
+  configure,
+  requireApproval,
+  verify
+};

package/package.json

@@ -1,52 +1,47 @@
 {
   "name": "@permission-protocol/sdk",
-  "version": "0.1.0-alpha.2",
-  "description": "Standardized authorization and receipts for autonomous AI actions",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for Permission Protocol",
+  "license": "MIT",
+  "author": "Permission Protocol",
+  "repository": {
+    "type": "git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
     "dist",
-    "README.md"
-  ],
-  "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"
+    "README.md",
+    "LICENSE"
   ],
+  "sideEffects": false,
   "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"
+    "build": "tsup src/index.ts --dts --format cjs,esm --clean",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
   },
+  "keywords": [
+    "permission",
+    "authorization",
+    "approval",
+    "sdk",
+    "typescript"
+  ],
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "@types/node": "^25.3.3",
+    "tsup": "^8.2.4",
+    "typescript": "^5.6.3"
   }
-}
+}