Skip to content

Implement BrowserAutomationReceipt and visible automation session controls#27

Draft
Copilot wants to merge 3 commits intomainfrom
copilot/implement-browser-automation-receipt
Draft

Implement BrowserAutomationReceipt and visible automation session controls#27
Copilot wants to merge 3 commits intomainfrom
copilot/implement-browser-automation-receipt

Conversation

Copy link
Copy Markdown

Copilot AI commented May 6, 2026

Browser automation transports could operate without any user-visible ownership, permission scope, or revocation path. This PR introduces a receipt-backed governance layer that makes every automation session explicit, visible, and revocable.

Schema & fixture

  • schemas/browser-automation-receipt.schema.json — JSON Schema 2020-12 definition enforcing stable receipt URN (urn:srcos:receipt:browser-automation:<hex>), transport enum, permission scope, origin, userVisible: true, revocable: true, policyDecisionRef, and conditional revokedAt (required when status = revoked).
  • examples/browser-automation-receipt.example.json — Fixture that validates against the schema.

Policy & UI surface

  • policy/automation-receipt-policy.yaml — Runtime rules: receipt required before transport starts; no owner → reject; no policy decision → reject; orphan events → quarantine, never silently accepted; compact receipt refs in logs (full topology only in explicit debug mode).
  • automation/automation-session-ui.yaml — Visible session surface spec: always-on badge/panel showing owner, transport, tab scope, permissions, origin, receipt ID, and a one-click revoke control that terminates the transport, invalidates the session token, sets revokedAt, and emits a provenance event.

Runtime integration

runtime/playwright-smoke.mjs now generates a receipt URN at session start and emits browser.automation.receipt events at every lifecycle transition:

// session start → active receipt emitted before transport opens
const activeReceipt = emitReceipt('active');

// policy denial → denied receipt, transport never starts
emitReceipt('denied');

// normal close → ended receipt
const endedReceipt = emitReceipt('ended');

All provenance events carry automationReceiptId for compact cross-referencing.

Verification

scripts/bearbrowser-verify-automation-receipt.py validates receipt files against the schema contract and includes a built-in --self-test covering all acceptance criteria:

Test case Expected
Successful local automation valid
Denied policy decision valid
Missing ownerRef invalid
Revoked with revokedAt valid
Revoked without revokedAt invalid
Orphan (no policyDecisionRef) invalid

Copilot AI and others added 2 commits May 6, 2026 18:20
…on controls

- Add schemas/browser-automation-receipt.schema.json with full receipt contract
- Add examples/browser-automation-receipt.example.json fixture
- Add automation/automation-session-ui.yaml for visible session surface
- Add policy/automation-receipt-policy.yaml for runtime governance rules
- Update runtime/playwright-smoke.mjs to emit automation receipts on start/end/deny
- Add scripts/bearbrowser-verify-automation-receipt.py with 6 acceptance-criteria tests
- Update docs/runtime-automation.md to document receipt lifecycle and revocation"

Agent-Logs-Url: https://github.com/SourceOS-Linux/BearBrowser/sessions/15431771-da06-4027-a77d-45212fbaa98c

Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>
Copilot AI changed the title [WIP] Implement BrowserAutomationReceipt and visible automation session controls Implement BrowserAutomationReceipt and visible automation session controls May 6, 2026
Copilot AI requested a review from mdheller May 6, 2026 18:23
Copy link
Copy Markdown
Contributor

mdheller commented May 6, 2026

Review: useful governance surface, but contract alignment is required before merge

This PR adds the right product surfaces: a receipt schema/fixture, policy rules, visible session UI spec, runtime event hooks, and a verification script. That is directionally correct.

Blocking remediation before ready/merge:

  1. Align the local schema and fixture to the upstream contract landed in SourceOS-Linux/sourceos-spec PR #101: schemas/BrowserAutomationReceipt.json and examples/browserautomationreceipt.json.
  2. The upstream contract requires capabilityLedgerRef, startedAt, terminalState, policyDecisionRef, non-empty evidenceRefs, and capturedAt. Make sure the local fixture and runtime event output include these exact fields.
  3. Avoid creating an unsynchronized parallel schema. Either copy the upstream schema with a comment indicating source commit, or add a clear sync/validation path from sourceos-spec.
  4. Ensure runtime lifecycle states map to upstream terminalState values: active, revoked, completed, failed, denied. The PR body mentions ended; if used internally, adapt it to completed in emitted receipts.
  5. The permission vocabulary should match upstream permissionScope enum from PR #101. If the repo uses friendlier UI labels, keep those as display labels but emit upstream enum values in the receipt.
  6. Add tests that validate emitted receipt payloads against the upstream schema or copied schema.

Recommendation: keep the UI/policy/runtime work, but add a small adapter layer that emits the SourceOS contract payload exactly, then validate the canonical example plus generated lifecycle examples.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Implement BrowserAutomationReceipt and visible automation session controls

2 participants