Protected files

protect keeps a file under your control after you share it: it stays ciphertext until a TAPS Node issues a licence, so you can time-release it, revoke it in seconds and see who opened it.

For a walk-through, see Protect a file so only the right people open it.

protect:
  driver: taps-node          # local in dev and tests
  url: https://taps.acme.dev
  share-domain: open.acme.dev
  key: secret:MAINSDK_PROTECT_KEY
  mode: viewer               # viewer | wrapper
  suite: TAPS-CS1            # TAPS-CS1 | TAPS-CS2
  renew: 10s                 # licence renewal, 5s to 5m
  mcp: false                 # true adds the taps_* tools to the MCP server

import { protect, share } from "mainsdk";

const asset = await protect(paper, { label: "sensitive", policy: { releaseAt: "2027-03-01T09:00:00Z" } });
const { url } = await share(asset, { to: examiners });   // a getqr.id link that opens the TAPS Web Reader

import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

const app = createTestApp({ yaml: "schema: 1\nproject: papers\n" });
const asset = await app.tenancy.as({ user: "u1" }, () =>
  app.protect(new TextEncoder().encode("Q1 paper"), { label: "sensitive" }),
);
const opened = await app.tenancy.as({ user: "u1" }, () => app.protect.open(asset.id));
assert.equal((await opened.text()).text, "Q1 paper");

protect:
  driver: local

Quick start

The local driver needs no setup. Protect a file, then share it. The share link is a getqr.id URL that opens the TAPS Web Reader.

protect:
  driver: local          # taps-node in production

import { auth, protect } from "mainsdk";

export async function POST(req: Request) {
  await auth.require(req, { role: "exam-admin" });
  const form = await req.formData();
  const paper = form.get("paper") as File;
  const examiners = form.getAll("examiner").map(String);

  const asset = await protect(paper, {
    label: "sensitive",
    policy: { releaseAt: "2027-03-01T09:00:00Z" },   // nobody opens it before this time
  });
  const { url } = await protect.share(asset.id, { to: examiners });
  return Response.json({ url, asset: asset.id });
}

use mainsdk::prelude::*;
let app = App::test();
Context::new().tenant("tnt_a").user("u1").scope(async {
let id = app.protect().open("u1", b"plan").await?;
app.protect().share(&id, "u1", "u2").await?;
assert_eq!(app.protect().get(&id, "u2").await?, b"plan");
Ok::<_, MainError>(())
}).await?;

Every call reads the tenant, the user and the agent from the request context. Outside a request, run the call as a person with tenant.as({ user }, fn); an explicit user or agent option overrides the context for one call and is audited. With no user, a call fails with MAIN-PROTECT-0015.

Configuration

protect:
  driver: taps-node                 # local | taps-node | taps-hosted | sovedocs
  url: https://taps.acme.dev        # the TAPS Node (not for local)
  share-domain: open.acme.dev       # where the Web Reader runs (not for local)
  key: secret:MAINSDK_PROTECT_KEY   # the app's issuer identity
  mode: viewer                      # viewer | wrapper
  suite: TAPS-CS1                   # TAPS-CS1 | TAPS-CS2
  renew: 10s                        # licence renewal, 5s to 5m
  threshold:
    board: https://taps.board.example
    regulator: https://taps.regulator.example
  mcp: false
  environment: https://seal.acme.dev

mainsdk check reports a bad section as MAIN-PROTECT-0021, a @taps/* import outside the driver package as MAIN-PROTECT-0020, a production build that resolves @taps/* from a folder as MAIN-PROTECT-0022, and the local driver in production as MAIN-CHECK-0026.

The policy

Policy is default deny and runs on every licence request and every renew. The owner is never restricted by their own policy.

Labels public, internal, confidential and restricted are the TAPS labels. personal maps to confidential; sensitive, child and phi map to restricted. The label pan is refused: card numbers are never protected or stored.

What you get

• A protected file carries its own identity, provenance and policy, and stays ciphertext until a TAPS Node issues a licence.
• Release at a set time, or when enough parties agree.
• Revoke in seconds, and see who opened it.
• App agents read it only inside a delegation.
• Use it for exam papers nobody can open early, tenders, results or any document you may need to pull back.
• Built on TAPS (Trust Anchor Provenance System), HubXero Labs' open protocol.

Calls

Lists return { items, next }. Changes that need a second pair of eyes (protect.erase(), protect.transfer(), lowering a label with protect.update(), protect.zones.update(), protect.lockdown.create() and .delete(), protect.leaks.trace()) take approvals from people other than the caller, and fail with MAIN-PROTECT-0005 without them.

Examples

Release an exam paper at a set time

Before releaseAt, no licence is issued and the attempt is written to the decision log and protect.activity().

import { protect } from "mainsdk";

export async function scheduleRelease(paper: File, examiners: string[]) {
  const asset = await protect(paper, {
    label: "sensitive",
    policy: { people: examiners, releaseAt: "2027-03-01T09:00:00Z" },
  });
  return asset.id;
}

Open a file

protect.open() asks for a licence for the current user or agent and returns nothing without one. A viewer gives pages and the accessible text layer; only mode: "wrapper" allows read(). text() returns { page, blocks, text }.

import { protect } from "mainsdk";

export async function readPaper(id: string) {
  const opened = await protect.open(id);
  try {
    return (await opened.text()).text;   // the text layer a screen reader uses
  } finally {
    await opened.close();
  }
}

Revoke a file in seconds

A revoked asset, person or link fails the next open and the next renew, so an open session stops within one renew interval.

import { auth, protect } from "mainsdk";

export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
  await auth.require(req, { role: "exam-admin", fresh: "5m" });
  const { id } = await params;
  await protect.revoke(id, { reason: "paper leaked" });
  return new Response(null, { status: 204 });
}

protect.revoke(id, { reason, person }) stops one person and leaves the rest.

See who opened a file

import { auth, protect } from "mainsdk";

export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  await auth.require(req, { role: "exam-admin" });
  const { id } = await params;
  const opens = await protect.activity(id);   // { items, next }
  return Response.json(opens);
}

Open only inside a network zone

import { protect } from "mainsdk";

export async function officeOnly(paper: File, approvedBy: string) {
  await protect.zones.update(
    { "z-7f3a": { name: "Head office", cidrs: ["203.0.113.0/24"] } },
    { approvals: [{ by: approvedBy }] },
  );
  return protect(paper, { label: "confidential", policy: { zones: ["z-7f3a"] } });
}

Zone ids are opaque; protect.policy.lint() flags a name such as head-office.

Require several parties to release

Name each party under protect.threshold in main.yaml first; a party that isn't named fails with MAIN-PROTECT-0015. For the local driver a name with no URL is enough:

protect:
  driver: local
  threshold: { board: null, regulator: null, centre: null }

import { protect } from "mainsdk";

export async function boardRelease(minutes: File) {
  const asset = await protect(minutes, {
    label: "restricted",
    policy: {
      threshold: { t: 2, parties: ["board", "regulator", "centre"] },
      releaseAt: "2027-03-01T09:00:00Z",
    },
  });
  return protect.threshold.get(asset.id);   // { t: 2, n: 3, released: [] }
}

No licence is issued until t parties have released their shares, and not before releaseAt when both are set.

Let an agent work within a delegation

An app agent acts only inside a delegation from the person it acts for, never wider than that person. An action in approve.for waits for the person's approval.

Run delegate.create as the person (in a signed-in request, or inside tenant.as({ user }, fn)): a delegation always starts with a person, and an agent can't make one (MAIN-PROTECT-0007).

import { protect } from "mainsdk";

export async function letReaderSummarise(assetId: string) {
  const delegation = await protect.delegate.create({
    agent: "reader-bot",              // declared under agents in main.yaml
    assets: [assetId],
    actions: ["view", "print"],
    purposes: ["summarize"],
    expiresIn: "1h",
    approve: { for: ["print"], timeout: "15m" },
  });
  return delegation.id;
}

export async function approvePrint(approvalId: string) {
  return protect.approvals.update(approvalId, { decision: "approve" });
}

protect.query() answers a question over protected assets without returning their bytes: answers are marked generated, carry citations and never hold a verbatim span over 25 tokens. An agent never approves its own request (MAIN-AGENT-0003).

Share through getqr.id

share(asset, { to }) and protect.share() return a getqr.id link and QR whose target is the TAPS link on your share domain. Outside the test kit they use your getqr.id key (secret:GETQR_API_KEY, see Share links and QR codes); the kit makes local links. The TAPS link token is never in the getqr.id path, in logs or in channel data, and every link page shows "Powered by getqr.id".

import { protect, share } from "mainsdk";

export async function sharePaper(assetId: string, email: string) {
  const link = await protect.share(assetId, { to: [email], expiresIn: "7d", maxOpens: 3 });
  return { url: link.url, id: link.id };
}

export async function stop(linkId: string) {
  await share.revoke(linkId);   // revokes the getqr.id link and the TAPS link
}

Reference

Every call also takes the call options user, agent and signal. Signatures are in mainsdk/protect.

Policy

Share links

A link is { id, url, qr, asset, expiresAt, opens }. The url and qr are getqr.id; the TAPS token is never in them. A link still being registered fails with MAIN-PROTECT-0017.

People

Delegations and approvals

MCP tools

Attestation, ledger and lockdown

Events

Building it yourself

mainsdk builds protect for you from main.yaml. These are for driver authors, tests and tools.

Protecting web requests is a different tool

protect guards files. The headers, CSRF checks, CORS rules and cookie flags that guard your web responses are inbound protection, and showing user or model text as safe HTML is sanitize; both are covered in that guide and have no interface page of their own.

Channels, logs and the ledger

Every decision and side effect goes on one of eight mainsdk:protect.* channels, to the decision log (log.audit, with the actor, on_behalf_of, purpose and policy hash) and to the ledger. Channel data is ids, codes and kinds only: never content, names, emails, tokens or IP addresses.

The local ledger is append-only and hash-chained. protect.ledger.verify() finds any edit, deletion or reorder, and protect.ledger.export() returns an in-toto Statement in a DSSE envelope, signed by the app's key. Security events are raised for protect.denied_burst (20 denials of one asset in a minute), protect.leak_reported, protect.lockdown and protect.quarantined; read them with protect.channels.security().

Errors and checks

See Errors for every MAIN-PROTECT-* code.

Swapping drivers

Change one line of main.yaml; no call changes.

protect:
  driver: taps-hosted   # was taps-node

The local driver is a fake for development and tests, never a Node: mainsdk check refuses it in production (MAIN-CHECK-0026). Assets protected on local stay in development; moving assets between drivers is not specified. A driver that lacks a capability says so in its profile (query, threshold, timelock, inspect, web3, delivery); the call then fails with MAIN-PROTECT-0019.

Testing

createTestApp() from @mainsdk/testing runs the local driver offline with the test clock, so releaseAt, time windows, renewal and expiry move with app.clock. Run each call as a person with app.tenancy.as().

import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

const app = createTestApp({ yaml: "schema: 1\nproject: papers\n" });
const asset = await app.tenancy.as({ user: "u1" }, () =>
  app.protect(new TextEncoder().encode("Q1 paper"), { label: "sensitive" }),
);
const opened = await app.tenancy.as({ user: "u1" }, () => app.protect.open(asset.id));
assert.equal((await opened.text()).text, "Q1 paper");

The kit adds app.protect.signals({ ip, country, confidence, managed, attested }), app.protect.party(name).release(asset) and .withhold(asset), and app.protect.chain(holdings). The suite in @mainsdk/testing runs every call on any driver and lists the cases a profile lacks as skipped, by name.

Security and privacy

• A protected file is ciphertext without a licence, wherever a copy ends up. Content keys are wrapped with keys, and every unwrap is an audit record.
• Each user is a tenant-pairwise principal to TAPS: no user id, email or name reaches a Node or ledger in clear.
• Every asset belongs to one tenant and opens only in its data region. Another tenant gets the same MAIN-PROTECT-0004 as for an unknown id.
• Every request to a Node, party or sealing service goes through the network layer, so the allowlist, timeouts and retries apply.
• MainSDK claims no post-quantum protection for protect. The TAPS-CS3 suite is refused until it is registered.

What Cloud adds

protect is free in your app. The Fleet plan adds an estate view of protected files and a response action to revoke every file an app or person shared since a date. See Free in-app and Cloud.

FAQ

How is this different from a share link? A share link controls the link; once someone downloads the file, the copy is theirs. A protected file stays ciphertext and asks the TAPS Node for a licence every time it opens.

Do readers need to install anything? No. Links open in the TAPS Web Reader.

What does not work offline or on local? Offline licences, the wrapper session's device-sealed keys and DRM key delivery are out of scope for 0.4. A TAPS Node, a threshold party and a sealing service are not run inside MainSDK.

Next

• TAPS Node and SoveDocs: the real drivers and how they install.
• Share links and QR codes: how protected files are shared.
• Policy decisions: the decision log opens are written to.
• Free in-app and Cloud: what Fleet adds.