Safety rules for app authors

The rules every app is held to, written for the person building one.

An app that collects names and addresses carries a promise to those people. Respira Code cannot keep it for you, but it makes the common mistakes hard. The steps below are in the order to work in. Nothing here is legal advice.

1. Draw the data map first

Declare every table that holds personal data in personal_data: the table, its key, the email column, the columns, the purpose and the legal basis, and its child tables. Only tables the app owns are accepted, and WordPress users and WooCommerce orders are never reachable. Respira writes a policy stub per language from this declaration. It is text for you to review, not a page, and not legal advice.

"personal_data": [ {
  "table": "pen_pals_people", "pk": "id", "email_column": "email",
  "columns": ["writer_name", "email", "address", "birthdate"],
  "purpose": "Find a pen-pal and send two families each other's address.",
  "basis": "consent",
  "children": [ { "table": "pen_pals_mail", "fk": "pen_pal_id" } ]
} ]

2. Give every kind of data an end

Add retention rules (see Primitives). A rule on a table with a status column must say which statuses. The owner approves each rule with a count of what it would delete, so a rule written too wide is caught before it deletes anything. The lint checks the shape of every retention rule.

3. Put an erasure link in every letter

Use {{respira.delete_link}} in every kind that goes to a person, and the unsubscribe link in every many kind. Erasure keeps no copy, and the address hash stays on a suppression list so nobody is written to twice.

4. The owner-only rule

Some acts are a person's, never an agent's: the setup wizard, giving a key developer access, releasing the kill switch, approving a destructive step, adopting a table, setting a secret and acknowledging consent. WordPress signs the key's user in on REST requests, so current_user_can() alone does not prove a human is at wp-admin. Respira refuses these acts for any request that carries a Respira key, an application password or an Authorization header. If your app adds an owner-only act, do the same: make the permission callback \respira_app_owner_request(), and use a nonce on a wp-admin form. The lint warns when a permission callback checks a capability and nothing else. Owner and abilities has the whole model.

A deployed app is code

A key with developer:apps can deploy PHP, which amounts to running code on the site. For that reason an owner's approval never binds code an agent deployed. The lint refuses calls into Respira Code's own internals and the names it reserves, and the loader refuses whatever the lint refuses, so a release that gets past one does not get past the other.

The limit to know about

App code that runs inside the owner's own wp-admin page load cannot be told apart from the owner, because it runs in the same process. That is why approvals and secrets are decided on plain owner requests, and why owners should deploy only code they have read or had reviewed. Secrets are set only by the owner, in wp-admin.

What may not be built

Respira Code is for building things a site owner would be glad to show their visitors. It may not be used to build:

  • Anything that collects card or payment details outside the shop's own payment provider.
  • Pages or forms that imitate another brand, a login or a bank to collect passwords or personal details.
  • Email to people who did not ask for it, or email that hides who sent it.
  • Anything hidden from the site owner: accounts, links, redirects, content, or code that disguises what it does.
  • Showing search engines or AI crawlers something different from what visitors see.
  • Collecting personal data without telling the person, or without a way to delete it.
  • Scanning, attacking or overloading other sites, or mining with the site's server.

Respira does not see what a person types to their agent. It sees the code the agent uploads. The agent reads these same rules in the site brief and is told to refuse a request to build any of the above. The upload check refuses code that hides what it does, runs text as code, runs shell commands, or writes files outside the app. It does not judge intent: it cannot tell an honest form from a dishonest one, so a page that breaks these rules can still pass it.

That is why the site owner is the other check. The owner allows each app's first deploy and sees what the release contains before it goes live, and the off switch below stops every app.

A licence used to build these things can be ended. To report abuse, write to word@respira.press.

Honest limits

  • App code runs with the same power as any plugin on the site. The upload lint and the owner's approval of each app's first deploy stand in front of it. An app that hides what it does can get past a lint. Read the code you deploy, or have it read.
  • The off switch stops every key and every app. Use the button on the Respira Code screen, a file at wp-content/respira-apps/.disabled, or define( 'RESPIRA_APPS_DISABLED', true ); in wp-config.php. The file and the line work even when wp-admin is down.
  • A key given access until it is switched off is only as safe as the apps installed on that site. Choose a shorter window, 24 hours, 7 days or 30 days, on sites where other people deploy.
  • Only the site owner can give a key developer access. A key or an agent's request cannot give itself developer access. The owner does it in wp-admin, and the Disarm button on a key takes it back at once.
  • WordPress multisite is not supported.

What an upload may not touch is on the upload lint page.

What agents can and cannot do

  • Can, while a key has developer access, for the time the owner chose: upload and deploy, run tests, roll back, read guarded SQL, run a write after its dry run, read logs, send a test letter and run a job.
  • Cannot: install the add-on, finish the wizard, give itself developer access, release the kill switch, set or read a secret, approve its own step, adopt a table, lift a mail hold, send a batch without a receipt, or resend a letter.
  • Refusals are final. If a rule blocks the agent, it says so and asks the owner. It does not work around it.

What is audited

Every write leaves an audit row with the action, the app, the release, the key and the result. A write must name its snapshot ids, or the audit refuses it and the action stops. Mail, secrets and erasure cannot be snapshotted, so their rows carry a ledger id instead: mail-<id>, sec:<app>:<NAME>:<version> or erase-<id>. Secrets are stripped from the row by name and by value. The log is at GET /respira-code/v1/audit.

How undo works

One session undo puts back what the session changed: release pointers, options, tables. A key that did not make a change cannot undo it without the owner. Three things do not come back: sent mail, erased people, and snapshots of personal data older than 30 days. That is by design. Undo must never be a way to resend a letter or to restore someone who asked to be forgotten.