# Document Permission Unlocker & Authorized Recovery Gateway (`offerastudio/document-permission-unlocker`) Actor

Analyzes document lock state, removes non-opening permission restrictions where possible, and submits authorized password recovery jobs to a private backend.

- **URL**: https://apify.com/offerastudio/document-permission-unlocker.md
- **Developed by:** [Offera Studio](https://apify.com/offerastudio) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Document Permission Unlocker & Authorized Recovery Gateway

Secure, enterprise-grade document lock analysis, permission restriction removal, and authorized password recovery for PDF, DOCX, XLSX, PPTX, and archive files.

### What It Does

Upload a locked or restricted document. The Actor analyzes the protection type and takes the appropriate action:

| Protection Type | Action | Pricing Event |
| :--- | :--- | :--- |
| **Analysis only** | Lock state report, encryption details, feasibility assessment | `document-analysis-and-job-setup` · $0.29 |
| **Edit / print / copy restrictions (no open password)** | Removes restrictions instantly, delivers clean, unprotected file | `permission-unlocked` · $2.99 |
| **Open password (PDF, Office, or archive file)** | 10-minute fast dictionary recovery attempt (charged per attempt whether or not the password is found) | `quick-recovery-micro-block` · $1.99 |
| **Open password (complex / unknown)** | 30-minute compute block running exhaustive multi-phase recovery, fully resumable (charged per attempt whether or not the password is found) | `recovery-compute-block` · $4.99 |

*Analysis and permission unlock deliver deterministic results. For password recovery tiers, charges cover dedicated hardware compute time; recovery cannot be unconditionally guaranteed.*

### Supported File Types

| Format | Permission Unlock | Recovery |
| :--- | :---: | :---: |
| **PDF** (all standard encryption revisions) | ✅ | ✅ |
| **DOCX / XLSX / PPTX** (modern Office, OOXML) | ✅ | ✅ |
| **DOC / XLS** (legacy binary Office, OLE2) | ❌ | ✅ |
| **ZIP, RAR, 7z** (encrypted archives) | ❌ | ✅ |

**Unsupported or unrecognized files:** If an unsupported format or custom encryption variant is detected, you are charged **$0.00**. An automated alert is routed to our engineering team and support for that variant will be added in a future release.

### Common Use Cases

- **Forgotten personal password** — You password-protected a tax return or family document years ago and no longer remember the password.
- **Former employee handover** — A colleague left the company and their password-protected spreadsheets are blocking a quarterly close.
- **Archived corporate documents** — Legacy files from a previous CRM, ERP migration, or M\&A archive locked with unknown credentials.
- **IT incident recovery** — A departing administrator locked shared templates or policy documents; IT needs to restore access for the team.
- **Permission-locked PDFs** — Contract PDFs or government forms with edit/print restrictions that prevent legitimate annotation, form-filling, or archiving workflows.

### How to Use

#### Mode 1: Submit a Document

```json
{
  "mode": "submit",
  "fileUrl": "https://example.com/locked-report.pdf",
  "ownershipType": "corporate",
  "recoveryReason": "former_colleague",
  "authorizationEvidence": "Q3 financial summary created by former CFO Jane Doe. I am the current CFO requesting access for the annual audit. Internal ticket reference: IT-2024-4481.",
  "contactEmailOrNotes": "jane.smith@company.com / IT-2024-4481",
  "acceptDisclaimer": true,
  "allowPrivateRecovery": true,
  "recoveryTier": "standard"
}
```

> **Tip:** Including a verifiable reference — such as a corporate email address, an internal ticket number, or an enterprise document system reference — in `authorizationEvidence` or `contactEmailOrNotes` strengthens your request. Requests that cannot be verified are subject to rejection during compliance review.

**Output:** Lock analysis report + job ID (if password recovery is required). If permission restrictions were removed, a direct public download link to the cleaned document is delivered.

#### Mode 2: Check Recovery Status

```json
{
  "mode": "check",
  "jobId": "rec_abc123xyz"
}
```

**Output:** Current job status. Once completed, the recovered password is delivered directly to your Apify dataset.

#### Mode 3: Extend a Running Job

```json
{
  "mode": "extend",
  "jobId": "rec_abc123xyz",
  "recoveryBlocks": 2
}
```

**Output:** Allocates additional 30-minute compute blocks and resumes seamlessly from the exact checkpoint — no repeated work.

### Transparent Pay-Per-Event Pricing

Each run charges **at most one** event corresponding to the action performed. No hidden fees, no double billing.

| Event | Price | What You Get |
| :--- | :--- | :--- |
| `document-analysis-and-job-setup` | **$0.29** | Full lock state analysis, container format inspection, and recovery feasibility report. |
| `permission-unlocked` | **$2.99** | Restriction-free document delivered with direct download link (analysis included). |
| `quick-recovery-micro-block` | **$1.99** | 10 minutes of dedicated hardware-accelerated dictionary recovery (analysis included). Charged per attempt whether or not the password is found. |
| `recovery-compute-block` | **$4.99** | 30 minutes of dedicated multi-phase deep recovery per block (resumable, analysis included). Charged per attempt whether or not the password is found. |

**Unsupported file types and unrecognized encryption variants:** **$0.00** *(No charge applied)*.

### Security & Privacy

- **Local-only file processing** — Your original document is analyzed and handled entirely within the Actor's isolated runtime container. Document contents are never transmitted to recovery infrastructure.
- **Security fingerprint only** — Only a minimal, locally-derived representation of the document's lock parameters is submitted to the secure recovery cluster. Your file bytes never leave the Actor container.
- **Ephemeral document storage** — Cleaned documents and temporary processing files are held in short-lived storage and automatically purged immediately after the job finishes.
- **Results in your private Apify dataset** — Recovered credentials are written directly to your private Apify dataset and governed by Apify's security and data retention policies. The recovery cluster permanently redacts its own temporary records upon confirmed delivery.
- **Audit trail retention** — Request metadata (ownership type, business reason, authorization statement, and account reference) is logged for legal compliance and abuse prevention.
- **Mandatory ownership verification** — Every recovery request requires an authorization statement, ownership type, and business reason. Requests that fail compliance review are rejected without charge.
- **Bounded compute** — All recovery runs operate within pre-paid time blocks. There are no open-ended or unbounded background processes.

### FAQ

**Q: Is password recovery guaranteed?**\
No. You purchase dedicated hardware compute time. Passwords that appear in common lists or follow predictable patterns have high recovery rates. Long, random, or highly unique passwords may not be recoverable within reasonable compute windows.

**Q: How long does recovery take?**\
Permission unlocks are typically instant (under 30 seconds). The standard tier allocates a 10-minute compute window targeting high-frequency dictionary candidates. The extended tier runs in 30-minute compute blocks; each block continues a systematic, multi-phase recovery from exactly where the previous block finished.

**Q: How many extended blocks will I need?**\
It depends entirely on the password's characteristics, which cannot be known in advance. Passwords that follow common conventions are typically found within the initial blocks. After each block, you receive a status update and decide whether to purchase another block or stop. **You are never automatically charged beyond what you explicitly purchase.** Most users who see a recovery result achieve it within 1–3 blocks.

**Q: Is there a maximum cost?**\
You control your spend completely. Each extended block is a separate purchase ($4.99). You choose how many blocks to allocate upfront, inspect results at each step, and decide whether to continue. There are no recurring subscriptions and no surprise charges.

**Q: Can I track which specific phase the recovery is executing?**\
The recovery status (`mode: check`) indicates whether the job is running, completed successfully, paused on budget exhaustion (resumable), or fully exhausted. Internal attack algorithms are orchestrated automatically by our cluster and remain backend implementation details.

**Q: Can I buy more time if the first block did not find the password?**\
Yes. Use `mode: extend` with your `jobId`. Recovery resumes from the exact state and checkpoint where it paused — previously searched keyspaces are never repeated.

**Q: What file types are supported?**\
PDF (all standard encryption revisions), modern Office (DOCX, XLSX, PPTX), legacy binary Office (DOC, XLS), and encrypted archives (ZIP, RAR, 7z). Please refer to the Supported File Types table above.

**Q: My file type or encryption variant is not supported yet — will it be?**\
If your document utilizes an unrecognized encryption scheme, you are charged **$0.00** and an automated alert is sent to our engineering team. Support for new formats is added in rolling updates.

**Q: What happens to my file after processing?**\
It is automatically erased from the Actor's container storage. Cleaned files from permission unlocks remain accessible through your Apify account's key-value store according to your retention settings.

**Q: Where is the recovered password stored?**\
It is written strictly to your private Apify dataset, accessible only by your authenticated Apify account. The compute cluster permanently clears its own temporary cache upon delivery.

**Q: Why do I need to provide an authorization statement?**\
All high-assurance recovery requests undergo verification. The authorization statement, combined with your ownership type and recovery reason, establishes a tamper-evident audit record. Requests with insufficient justification are rejected to prevent unauthorized use.

# Actor input Schema

## `mode` (type: `string`):

submit a new document job, check an existing recovery job, or extend (buy more time to continue) a resumable job.

## `fileUrl` (type: `string`):

Directly accessible file URL for submit mode.

## `fileBase64` (type: `string`):

Alternative upload path for submit mode. Keep files small; the Actor deletes temporary data after analysis.

## `fileName` (type: `string`):

Original file name when using Base64 input.

## `jobId` (type: `string`):

Job ID returned by submit mode. Required for check mode.

## `passwordHint` (type: `string`):

Optional user-provided hint, such as remembered words or date patterns.

## `ownershipType` (type: `string`):

Select whether this is a personal document or a corporate / enterprise document.

## `recoveryReason` (type: `string`):

Primary reason for requesting password recovery.

## `contactEmailOrNotes` (type: `string`):

Optional contact email, company domain, or internal ticket reference.

## `authorizationEvidence` (type: `string`):

Explanation of ownership or authorized custody (e.g. context of creation, document details). Minimum 20 characters.

## `acceptDisclaimer` (type: `boolean`):

I confirm I own this file or am authorized to recover access, and I understand recovery is not guaranteed.

## `allowPrivateRecovery` (type: `boolean`):

Submit an authorized password recovery job when the file requires an open password. Requires backend configuration and review policy.

## `recoveryTier` (type: `string`):

standard = fast 10-minute dictionary micro-block. extended = deep 30-minute attempt per block (26-stage masks + rules + dictionaries, resumable).

## `recoveryBlocks` (type: `integer`):

Extended tier only: how many compute blocks to buy now. Each block is 30 minutes of dedicated recovery cluster time. You can later run mode=extend to continue from where it stopped.

## Actor input object example

```json
{
  "mode": "submit",
  "ownershipType": "personal",
  "recoveryReason": "forgotten_password",
  "acceptDisclaimer": false,
  "allowPrivateRecovery": false,
  "recoveryTier": "standard",
  "recoveryBlocks": 1
}
```

# Actor output Schema

## `results` (type: `string`):

Direct API URL to the JSON items in the default dataset containing status, lock analysis, and unlocked document records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("offerastudio/document-permission-unlocker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("offerastudio/document-permission-unlocker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call offerastudio/document-permission-unlocker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,offerastudio/document-permission-unlocker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3aJuCZGOTBeEvp4Vz/builds/hh552xUAfyKRimsQv/openapi.json