From dbf2e682ea14d64dce5a5963cb4bb689b9cf5097 Mon Sep 17 00:00:00 2001 From: Jinwoo-H Date: Wed, 12 Aug 2026 09:15:09 -0400 Subject: [PATCH] docs(skills): publish sharing lifecycle guides --- ...-skill-sharing-implementation-checklist.md | 19 ++-- docs/agent-skill-sharing-installation-plan.md | 3 +- docs/reference/admin-agent-skill-sharing.md | 97 +++++++++++++++++++ .../agent-skill-sharing-threat-model.md | 5 +- docs/reference/sharing-agent-skills.md | 88 +++++++++++++++++ 5 files changed, 202 insertions(+), 10 deletions(-) create mode 100644 docs/reference/admin-agent-skill-sharing.md create mode 100644 docs/reference/sharing-agent-skills.md diff --git a/docs/agent-skill-sharing-implementation-checklist.md b/docs/agent-skill-sharing-implementation-checklist.md index dc045434e87..8098c42f134 100644 --- a/docs/agent-skill-sharing-implementation-checklist.md +++ b/docs/agent-skill-sharing-implementation-checklist.md @@ -1331,9 +1331,11 @@ metrics, lifecycle/migration visibility, budget coverage, and reviewed alert thr three explicit controls. - [ ] Disable the affected operation on unexplained digest mismatch, archive containment failure, data leak, unrecoverable local mutation, or cross-tenant authorization defect. -- [ ] Publish user documentation for sharing, access, install destinations, updates, rollback, - removal, retention, and trust. -- [ ] Publish admin documentation for organization access, user departure, deletion, and retention. +- [x] Publish user documentation for sharing, access, install destinations, updates, rollback, + removal, retention, and trust in + [`docs/reference/sharing-agent-skills.md`](./reference/sharing-agent-skills.md). +- [x] Publish admin documentation for organization access, user departure, deletion, and retention + in [`docs/reference/admin-agent-skill-sharing.md`](./reference/admin-agent-skill-sharing.md). - [ ] Remove rollout flags only after sustained healthy usage and a reviewed decision. ### First-release gate @@ -1344,8 +1346,10 @@ metrics, lifecycle/migration visibility, budget coverage, and reviewed alert thr - [ ] Real SSH paths and host-owned resolution pass. - [ ] Mixed-version tests pass in both directions. - [ ] Cancellation and crash recovery pass during transfer and every commit boundary. -- [ ] Durable-share authorization, revocation lag, retention, deletion, and recovery are documented - and tested. +- [x] Durable-share authorization, revocation lag, retention, deletion, and recovery are documented + and tested. The user/admin guides document the lifecycle; Cloud route, integration, restore, + and cleanup suites cover the implemented contract. Automatic one-day quarantine deletion + remains a separate time-gated infrastructure observation. - [ ] The UI identifies author, organization, scripts, and executable content before install. - [ ] Telemetry, logs, and diagnostic bundles contain no credentials or private contents. - [ ] Kill switches are tested without affecting discovery or existing installations. @@ -1360,5 +1364,6 @@ metrics, lifecycle/migration visibility, budget coverage, and reviewed alert thr - [ ] Evaluate an explicit, reviewable project desired-state manifest. - [ ] Evaluate direct machine-to-machine transfer if Cloud persistence is not appropriate. - [ ] Define offline convergence without durable shared credentials. -- [ ] Document organization removal, user departure, package retention, and reconciliation - semantics before enabling policy-driven installs. +- [x] Document organization removal, user departure, package retention, and reconciliation + semantics before enabling policy-driven installs. The admin guide explicitly leaves legal + retention and ownership-transfer approval as human release gates. diff --git a/docs/agent-skill-sharing-installation-plan.md b/docs/agent-skill-sharing-installation-plan.md index 2b8405e2305..61cfa3b6957 100644 --- a/docs/agent-skill-sharing-installation-plan.md +++ b/docs/agent-skill-sharing-installation-plan.md @@ -1154,7 +1154,8 @@ The detailed threat register and residual release gates live in - Treat `SKILL.md` and packaged scripts as executable code for trust messaging. - Show author, organization, version, digest, file summary, and executable files before install. -- Require authentication for private share resolution and every download grant. +- Require the exact active bearer share ID for recipient resolution and every download grant; + require authentication for publication and owner management. - Bind grants to one package version, digest, maximum byte count, and short expiration. - Validate grant and redirect hosts to prevent server-side request forgery. - Never execute package scripts during installation. diff --git a/docs/reference/admin-agent-skill-sharing.md b/docs/reference/admin-agent-skill-sharing.md new file mode 100644 index 00000000000..1ea9a65d8ef --- /dev/null +++ b/docs/reference/admin-agent-skill-sharing.md @@ -0,0 +1,97 @@ +# Administer agent skill sharing + +This guide describes the first-release access, lifecycle, retention, and recovery contract for +Orca skill sharing. The operator runbook remains the source of truth for incident commands and +environment-specific procedures. + +## Access model + +- Shared bundles are unlisted bearer resources. Orca provides no public browse, search, recipient + inventory, or package index. +- Anyone with an active, unexpired link can inspect the package and request a short-lived download + grant without signing in. +- Publishing, package/version management, owned-link inventory, revocation, and deletion require + an authenticated package owner with current organization access. +- Missing, expired, revoked, deleted, and unauthorized resources return the same non-disclosing + response. +- Desktop and remote runtimes receive no GCP identity or long-lived storage credential. + +The durable share ID is a credential. Do not put it in tickets, logs, analytics, or support +bundles. Use revocation if a link may have reached an unintended recipient. + +## Revocation and deletion + +Revoking a share immediately blocks new resolution and download grants. A generation-bound grant +issued before revocation can work until its five-minute expiry. Already installed skills remain on +recipient machines. + +Package deletion follows this order: + +1. Mark the package deleted and revoke its active shares. +2. Dereference retained versions transactionally. +3. Delete only an object generation that no retained version references. +4. Reconcile bounded pending deletions after partial database or GCS failures. + +A version cannot be deleted while an active pinned share references it. Deletion uses the exact +recorded GCS generation and never overwrites an immutable published key. + +## User and organization departure + +Packages belong to an owner tenant and record the publishing user. In an organization tenant, +another current member can manage the package after its publisher leaves; Orca does not rewrite +the recorded creator. Removing a user does not automatically revoke the organization's links, +delete packages, or remove installed copies. + +Before deleting an organization tenant: + +1. Disable new grants for the tenant. +2. Have an authorized operator inventory and revoke active shares. +3. Decide whether packages transfer to another authorized owner, remain retained, or are deleted. +4. Resolve legal hold, erasure, and audit-retention requirements. +5. Apply the coordinated metadata and object lifecycle; do not bypass reference checks. + +The product does not yet encode a universal ownership-transfer or legal-retention policy. Privacy, +security, and the organization owner must approve the applicable policy before external rollout. +Until that decision is recorded, preserve metadata and soft-deleted generations rather than +guessing. + +## Retention contract + +| Data | Default behavior | +| -------------------------------------- | --------------------------------------------------------- | +| Upload policy and pending upload row | Expires after 15 minutes | +| Abandoned `uploads/` quarantine object | Deleted by GCS after one day | +| Published immutable package object | No age-based deletion; retained while referenced | +| Issued download grant | Expires after five minutes | +| Deleted package object | Recoverable through GCS soft delete for seven days | +| PostgreSQL metadata | Covered by backups and seven-day point-in-time recovery | +| Installed recipient copy | Independent local data; Cloud deletion does not remove it | +| Audit event | Follows the approved audit-retention policy | + +Organization retention, legal hold, and erasure requirements take precedence over product rollback +retention. Product deletion is not a legal-hold mechanism. + +## Audit and privacy + +Audit records may include package/version IDs, actor IDs, event category, outcome, and timestamp. +They must not include skill contents, filenames, manifests, organization membership lists, local +paths, durable share URLs, upload policies, download grants, or credentials. Anonymous abuse +controls must not persist raw requester IP addresses. + +Normal Cloud logs are limited to route, method, status, duration, and bounded failure categories. +Use seeded privacy canaries when validating staging logs and diagnostic exports. + +## Recovery and incident controls + +Upload, download, and remote-install operations have independent kill switches. Disable the +narrowest affected operation; existing local discovery and installs continue to work. + +Coordinate PostgreSQL point-in-time recovery with GCS generation recovery. Restore metadata into +an isolated database, identify exact referenced generations, restore only matching soft-deleted +objects, verify archive and package identities, then transactionally repoint metadata. Keep grants +disabled until bearer preview and a generation-bound download pass. + +See the Orca Cloud `docs/skill-sharing-runbook.md` for deployment controls, reconciliation, +saturation, signing failures, database outages, and the guarded restore workflow. Security +invariants and unresolved release gates are recorded in +[Agent skill sharing threat model](./agent-skill-sharing-threat-model.md). diff --git a/docs/reference/agent-skill-sharing-threat-model.md b/docs/reference/agent-skill-sharing-threat-model.md index a41e75e5197..d9b445d7302 100644 --- a/docs/reference/agent-skill-sharing-threat-model.md +++ b/docs/reference/agent-skill-sharing-threat-model.md @@ -10,7 +10,8 @@ resolution, local and remote installation, provider placement, update, rollback, operator recovery. It applies to macOS, Linux, native Windows, WSL, paired Orca runtimes, and SSH targets. -Private means access-controlled to authenticated Orca users and organizations. V1 is not +Private means unlisted: an unpredictable active share ID is a bearer credential, while publication +and management remain access-controlled to authenticated Orca users and organizations. V1 is not end-to-end encrypted from Orca Cloud operators. A skill is code from its author: `SKILL.md` can change agent behavior and packaged scripts may be executed later by a user or agent, although the installer itself never executes package content. @@ -71,7 +72,7 @@ Trust boundaries are: | TM-06 | A crash between renames or receipt publication loses both old and new versions. | Same-filesystem staging, durable journals, backups, flushed receipt replacement, bounded recovery, and ownership tokens protect every commit boundary. Failure injection covers every journal transition. | Real process termination and disk/antivirus contention tests remain required. | | TM-07 | A grant leaks through redirects, userinfo, an insecure scheme, DNS/host confusion, or an oversized stream. | Cloud requests reject redirects. Package downloads require configured origins and HTTPS, reject URL credentials and cross-origin redirects, cap redirect count, recheck expiry, stream exact expected bytes, and verify archive/package digests. | Validate approved production origins and exercise malicious network cases in staging. | | TM-08 | Reuse of an upload ID, wrong tenant, wrong key, stale generation, or quarantine object publishes attacker-selected bytes. | Random tenant-bound upload rows, signed POST conditions, expiry, exact metadata/key/type/size validation, generation-fenced reads, streamed validation, and idempotent finalization fail closed. | Staging GCS integration must cover stale generations and lifecycle deletion. | -| TM-09 | IDOR or stale organization membership exposes package metadata or creates a fresh grant. | Every resolution and grant request authenticates and re-evaluates current package/share ACLs. Membership removal is tested between preview, grant, and download. Not-found responses hide unauthorized existence. | Human authorization review and organization-departure policy approval remain required. | +| TM-09 | IDOR, stale organization membership, or a guessed identifier exposes package management data or bearer-protected content. | Management requests authenticate and re-evaluate current ownership. Recipient preview and grants require the exact unpredictable, active bearer share ID and ignore legacy ACL rows. Not-found responses hide unauthorized existence. | Human authorization review and organization-departure policy approval remain required. | | TM-10 | Content-addressed deduplication discloses another tenant's package through response shape or timing. | Tenant-scoped APIs never expose GCS keys, generations, or whether an object already existed; existing-object reuse verifies both archive and logical package identity. | A staging timing test and reviewed mitigation threshold are still required before external rollout. | | TM-11 | A compromised renderer, old client, or arbitrary RPC caller sends credentials, local paths, unknown opcodes, or unsupported operations to a host. | Main owns auth tokens and grants; remote requests use strict schemas and capabilities; package transfer is separate from install; no stream opcode was added; mixed versions fail with update-required results. | Real client-newer/server-newer and SSH parity gates remain required. | | TM-12 | Transfer replay, overlap, disconnect, or abandoned staging consumes disk or commits different bytes. | Session count, idle time, total bytes, and chunk size are bounded. Offsets are monotonic, identical retry is idempotent, changed replay fails, commit hashes the exact staged file, and cancellation/disconnect cleanup is bounded. | Exercise offline-GCS and real disconnects at every transfer boundary. | diff --git a/docs/reference/sharing-agent-skills.md b/docs/reference/sharing-agent-skills.md new file mode 100644 index 00000000000..9b9b53706a3 --- /dev/null +++ b/docs/reference/sharing-agent-skills.md @@ -0,0 +1,88 @@ +# Share and install agent skills + +Orca can put one skill or a bundle of skills behind one unlisted, revocable link. Shared bundles +do not appear in search, a catalog, or a public index. Anyone who has an active link can inspect +and install its contents without signing in, so treat the link like a credential. + +## Share skills + +Publishing and link management require an Orca account in the desktop app. + +1. Open **Skills** and choose **Share skills**. +2. Select one or more skills. One link can contain a large collection, such as 30 skills. +3. Review the bundle name, included skills and files, scripts, executable files, digest, account, + and optional release notes. +4. Choose **Publish skill**, **Publish bundle**, or **Publish new version**, then copy the link. + +Orca publishes an immutable version. Later changes do not silently alter a link's current bytes; +publish a new version to update the Cloud package. + +Use **Settings → Share Skills** to copy or revoke active links. Revocation blocks new previews and +download grants. A grant issued immediately before revocation can remain usable for up to five +minutes, and revocation does not remove copies that recipients already installed. + +## Install from a link + +Opening an Orca skill link shows a preview before changing any files. You can also open **Skills**, +choose **Install from link**, and paste the URL. + +1. Verify the author and organization. +2. Review the version, release notes, included skills, scripts, executable files, and digest. +3. Select all skills or only the ones you want. +4. Choose the destination machine and either global or workspace scope. +5. Review new, unchanged, updated, and conflicting skills, then choose **Install N skills**. + +Supported destinations include the local machine, paired Orca runtimes, WSL, and SSH hosts. The +destination runtime resolves its own home and workspace paths, so folder workspaces and remote +filesystems do not borrow paths from the client machine. + +Orca keeps one canonical installed copy and places it where supported agents can discover it. +Current provider coverage is documented in +[Agent skill provider paths](./agent-skill-provider-paths.md). + +## Conflicts, updates, and rollback + +**Keep local** is the default when an existing skill differs. Orca replaces modified content only +after you explicitly choose to discard it. + +Open **Skills → Manage installs** to inspect managed skills and their immutable version history. +Installing the latest version performs an update; selecting an older retained version performs a +rollback. Both use the same protected install transaction. If a bundle changes between versions, +Orca updates only the selected skills that still exist in that version. + +An interrupted install is recovered on restart. If Orca reports a conflict or partial result, +review the named skill and retry; completed skills do not need to be installed again. + +## Remove an installed skill + +Use **Skills → Manage installs → Remove**. Orca removes only copies and provider placements that it +owns and can verify. Modified or unowned files are preserved and reported. Discarding modified +content requires a separate explicit confirmation. + +Removing a local install does not revoke its share or delete its Cloud package. Likewise, +revoking or deleting Cloud data does not reach into recipients' machines. + +## Retention and deletion + +- Upload grants expire after 15 minutes. +- Abandoned upload bytes are removed from quarantine after one day. +- Published versions have no automatic age-based deletion. +- Deleting a package revokes its links before unreferenced objects are deleted. +- Deleted GCS objects remain operator-recoverable through a seven-day soft-delete window. +- Installed copies remain until someone removes them on each destination machine. + +Organization legal or retention requirements can override normal rollback and deletion timing. + +## Trust and privacy + +A skill is code from its author. `SKILL.md` can change agent behavior, and included scripts or +executables may run later when a person or agent uses the skill. Orca validates the package and +never executes its contents during installation, but you should install only from people you trust +and review unexpected scripts or executable files. + +Orca records bounded operational identifiers and outcomes. Normal logs, telemetry, and support +bundles exclude skill contents, filenames, manifests, local paths, share URLs, upload policies, +download grants, credentials, and access lists. + +If a link no longer works, ask its owner for an active link. Missing, expired, revoked, and deleted +links intentionally show the same response so Orca does not disclose private package existence.