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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Permission Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,78 @@
-# Permission Protocol SDK
+# @permissionprotocol/sdk
 
-Standardized authorization and receipts for autonomous AI actions.
-
-> **No receipt = unauthorized autonomy**
+Official JavaScript/TypeScript SDK for Permission Protocol.
 
 ## Install
 
 ```bash
-npm i @permission-protocol/sdk
+npm install @permissionprotocol/sdk
 ```
 
-## Usage
+## Quickstart
 
-```typescript
-import { PermissionRouter } from '@permission-protocol/sdk';
+```ts
+import { configure, authorize } from "@permissionprotocol/sdk";
 
-PermissionRouter.configure({
-  endpoint: process.env.PP_ENDPOINT!,
-  apiKey: process.env.PP_API_KEY!,
-});
+configure("pp_live_xxx", "https://app.permissionprotocol.com");
+
+const receipt = await authorize(
+  "deploy",
+  "billing-service",
+  "deploy-bot",
+  { pr: 42 },
+  true,
+  300
+);
+
+console.log(receipt.id);
+console.log(receipt.status);
+console.log(receipt.valid);
+console.log(receipt.json());
+```
+
+You can skip `configure()` by setting:
+
+- `PP_API_KEY` (required)
+- `PP_BASE_URL` (optional, defaults to `https://app.permissionprotocol.com`)
+
+## API
+
+### `configure(apiKey, baseUrl?)`
+
+Set SDK credentials and API base URL.
+
+### `authorize(action, resource, actor?, metadata?, wait?, timeout?)`
+
+Create an approval request and return a `Receipt`.  
+When `wait` is `true` (default), the SDK polls until approved, denied, expired, or timeout.
+
+### `verify(receiptId)`
+
+Verify a receipt and return a `Receipt` with `.valid`.
+
+### `requireApproval(options)`
+
+Higher-order wrapper for function execution:
+
+```ts
+import { requireApproval } from "@permissionprotocol/sdk";
 
-const decision = await PermissionRouter.execute({
-  tenantId: 'acme',
-  agentId: 'example-agent',
-  tool: 'db.write',
-  operation: 'upsert_record',
-  input: { id: 123, value: 'hello' },
+const deploy = requireApproval({
+  resource: "billing-service",
+  action: "deploy"
+})(async () => {
+  return "deploy complete";
 });
 
-if (decision.status !== 'APPROVED') {
-  throw new Error(`Blocked: ${decision.status}`);
-}
+await deploy();
 ```
 
-## Learn more
+## Exceptions
 
-- [Receipt Standard](https://github.com/permission-protocol/reference/blob/main/docs/receipt-standard.md)
-- [Reference Demo](https://github.com/permission-protocol/reference/tree/main/reference-demo)
-- [CI Receipt Gate](https://github.com/permission-protocol/reference/tree/main/templates/github-actions/receipt-gate)
+- `PermissionProtocolError`
+- `PermissionDenied`
+- `ApprovalTimeout`
 
----
+## License
 
-This SDK is intentionally minimal.  
-Policy evaluation and enforcement live in the hosted Permission Protocol.
+MIT

package/dist/index.cjs

@@ -0,0 +1,274 @@
+"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, {
+  ApprovalTimeout: () => ApprovalTimeout,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  PermissionDenied: () => PermissionDenied,
+  PermissionProtocolError: () => PermissionProtocolError,
+  Receipt: () => Receipt,
+  authorize: () => authorize,
+  configure: () => configure,
+  requireApproval: () => requireApproval,
+  verify: () => verify
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/exceptions.ts
+var PermissionProtocolError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PermissionProtocolError";
+  }
+};
+var PermissionDenied = class extends PermissionProtocolError {
+  constructor(message = "Permission was denied.") {
+    super(message);
+    this.name = "PermissionDenied";
+  }
+};
+var ApprovalTimeout = class extends PermissionProtocolError {
+  constructor(message = "Approval request timed out.") {
+    super(message);
+    this.name = "ApprovalTimeout";
+  }
+};
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://app.permissionprotocol.com";
+var configuredApiKey;
+var configuredBaseUrl;
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+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 {
+    apiKey: configuredApiKey,
+    baseUrl: configuredBaseUrl
+  };
+}
+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 {
+    apiKey,
+    baseUrl: normalizeBaseUrl(baseUrl)
+  };
+}
+
+// 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/sdk.ts
+var import_node_os = require("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));
+  }
+  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(
+      getErrorMessage(response.status, `Failed to fetch receipt ${receiptId}`, body)
+    );
+  }
+  if (body && typeof body === "object" && "receipt" in body) {
+    return body.receipt;
+  }
+  return body;
+}
+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 body;
+}
+
+// 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 ?? (0, import_node_os.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;
+    }
+    if (currentReceipt.status === "DENIED" || currentReceipt.status === "EXPIRED") {
+      throw new PermissionDenied(`Approval request ${receipt.id} ended with status ${currentReceipt.status}.`);
+    }
+    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.`
+  );
+}
+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
+      );
+      return fn(...args);
+    };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApprovalTimeout,
+  DEFAULT_BASE_URL,
+  PermissionDenied,
+  PermissionProtocolError,
+  Receipt,
+  authorize,
+  configure,
+  requireApproval,
+  verify
+});

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+declare const DEFAULT_BASE_URL = "https://app.permissionprotocol.com";
+interface SDKConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+declare function configure(apiKey?: string, baseUrl?: string): SDKConfig;
+
+declare class PermissionProtocolError extends Error {
+    constructor(message: string);
+}
+declare class PermissionDenied extends PermissionProtocolError {
+    constructor(message?: string);
+}
+declare class ApprovalTimeout extends PermissionProtocolError {
+    constructor(message?: string);
+}
+
+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 AuthorizeParams {
+    action: string;
+    resource: string;
+    actor?: string;
+    metadata?: Record<string, unknown>;
+    wait?: boolean;
+    timeout?: number;
+}
+interface VerifyResponse {
+    valid: boolean;
+    receipt?: ReceiptData;
+    [key: string]: unknown;
+}
+
+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;
+}
+
+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 { ApprovalTimeout, type AuthorizeParams, DEFAULT_BASE_URL, PermissionDenied, PermissionProtocolError, Receipt, type ReceiptData, type ReceiptStatus, type RequireApprovalOptions, type SDKConfig, type VerifyResponse, authorize, configure, requireApproval, verify };